はじめに

GruntとGruntプラグインはNode.js パッケージマネージャーであるnpmを使用してインストールと管理を行います。このドキュメントはGrunt 0.4.xのために書かれていますが、Grunt 0.3.xについてもまだ有効です。ただ、0.3.xでのプラグイン名とタスクの構成オプションが"Gruntfile"の項目のものとは異なる場合がありますので、注意してください。

CLIのインストール
CLIの動作について
存在するgruntプロジェクトの動作
新しいgruntプロジェクトの準備
package.json
GruntとGruntプラグインのインストール
Gruntfileについて
更に詳しく知るために

CLIのインストール

もし、過去にgruntをグローバル上にインストールしていた場合、まず始めにそれを削除する必要があります。

npm uninstall -g grunt

最初にするべきことは、gruntのコマンドラインインターフェース(CLI)をグローバル上にインストールすることです。これを行うためには、sudo(OSX, Unix系, BSD等)または、管理者権限(Windows等)でコマンドシェルを実行する必要があるかもしれません。

npm install -g grunt-cli

どのフォルダからでも実行できるように、システムパス(PATH)にgruntコマンドを追加します。

インストールするgrunt-cliはgruntのタスクランナーにインストールされない事に注意してください。 gruntのCLIの仕事はシンプルです。Gruntfileと同階層のgruntをそのバージョンで実行します。これにより、同じマシンに複数のバージョンのgruntをインストールすることが可能になっています。

CLIの動作について

gruntは実行されると、ローカルにインストールされているgruntをnodeのrequire()を使って探します。これは、プロジェクト内のどのサブフォルダからでもgruntを実行できるようにするためです。

インストールされているGruntが見つかれば、CLIはローカルにインストールされたgruntのライブラリを読み込み、 Gruntfileの設定を適用して、タスクを実行させます。

実際に何が起こっているのかを理解したければ、コードを読んでみてください。とても短いです。

存在するgruntプロジェクトの動作

GruntのCLIがインストールされていて、プロジェクトが既にpackage.jsonとGruntfileによってされているのであれば、 Gruntを使って非常に簡単に始めることが出来ます。

プロジェクトのルートディレクトリに移動します。
プロジェクトに依存しているものをnpm installによってインストールします。
gruntで、Gruntを実行します。

本当にこれだけです。インストールされたGruntのタスクはgrunt --helpによってリスト表示されますが、通常はプロジェクトのドキュメントに沿って開始することをお勧めします。

新しいgruntプロジェクトの準備

プロジェクトにpackage.jsonとGruntfileの2つのファイルを追加します。

package.json:: このファイルは、npmモジュールのような公開されたプロジェクトのためのメタデータ情報を格納するために npmによって使用されます。プロジェクトにてgruntとGruntプラグインを列挙するには、このファイル内に devDependencies が必要です。
Gruntfile:: このファイルは、Gruntfile.jsまたはGruntfile.coffeeのどちらかをファイル名にする事ができ、タスクの設定、定義、Gruntプラグインのロードに使用されます。 0.3.xのバージョンでは、grunt.jsというファイル名でした。

package.json

package.jsonファイルはプロジェクトのルートディレクトリに配置し、Gruntfileも同階層に置いてプロジェクトのソースとしてコミットされるべきです。 package.jsonファイルと同じ階層でnpm installを実行すると、そのファイル内の依存リストに記述されたバージョンをインストールします。

プロジェクトにpackage.jsonファイルを作成する何通りかの方法を下記に示します。

大抵の場合、grunt-initを実行することで、自動的にプロジェクト用のpackage.json用のファイルを生成します。
npm initコマンドは基本的なpackage.jsonファイルを生成します。
下記の例を参考に始めてみてください。また必要に応じて npmのjsonページを参照して拡張してみてください。

{
  "name": "my-project-name",
  "version": "0.1.0",
  "devDependencies": {
    "grunt": "~0.4.0",
    "grunt-contrib-jshint": "~0.1.1",
    "grunt-contrib-nodeunit": "~0.1.2"
  }
}

GruntとGruntプラグインのインストール

package.jsonが存在する状態で、GruntとGruntプラグインを追加する最も簡単な方法は npm install <module> --save-devコマンドを使用することです。ローカルに<module>をインストールするだけで無く、 devDependencies内に自動的に~を使用したバージョン範囲の指定を追加してくれます。

例えば、下記のようにすると最新のバージョンのGruntがプロジェクトフォルダにインストールされ、 devDependenciesにもそれが追加されます。

npm install grunt --save-dev

Gruntプラグインとその他のnodeモジュールについても同様です。完了したら、更新したプロジェクトと一緒にpackage.jsonファイルをコミットしてください。

Gruntfileについて

Gruntfile.jsまたはGruntfile.coffeeは、有効なJavaScriptまたはCoffeeScriptのファイルで、プロジェクト内のルートディレクトリに存在し、同階層にpckage.jsonファイルがあり、プロジェクトのソースとしてコミットされるべきです。このファイルは、Gruntのバージョン0.3.xではgrunt.jsという名称でした。

Gruntfileは下記の項目によって構成されています。

"wrapper"関数
プロジェクトとタスクの設定
Gruntプラグインとタスクの読み込み
カスタムタスク

Gruntfileの例

下記のGruntfileでは、プロジェクトのメタデータはpackage.jsonファイルによってgruntの設定に取り込まれ、 grunt-contrib-uglifyプラグインのuglifyタスクは、ソースファイルを圧縮し、バナーコメントをメタデータを使用してダイレクトに生成するように設定されます。

gruntがコマンドライン上で実行されると、デフォルトでuglifyタスクが実行されるようになります。

module.exports = function(grunt) {

  // プロジェクトの設定
  grunt.initConfig({
    pkg: grunt.file.readJSON('package.json'),
    uglify: {
      options: {
        banner: '/*! <%= pkg.name %> <%= grunt.template.today("yyyy-mm-dd") %> */
'
      },
      build: {
        src: 'src/<%= pkg.name %>.js',
        dest: 'build/<%= pkg.name %>.min.js'
      }
    }
  });

  // プラグインのロードによって"uglify"タスクが提供されます。
  grunt.loadNpmTasks('grunt-contrib-uglify');

  // デフォルトのタスクを指定
  grunt.registerTask('default', ['uglify']);
};

これでGruntfileの内容がひと通り確認できました。次は構成要素について、確認しましょう。

"wrapper"関数について

各Gruntfile(とGruntプラグイン)はこの基本的なフォーマットが使用され、全てのGruntコードはこの中に書かれなければいけません。

module.exports = function(grunt) {
  // Gruntに関するコードをここに書いてください。
};

プロジェクトとタスクの設定

ほとんどのGruntタスクはgrunt.initConfigメソッドに渡されたオブジェクトで定義された構成データに依存しています。

この例では、grunt.file.readJSON('package.json')がpackage.jsonのJSONメタデータを gruntの設定にインポートしています。

<% %>テンプレート文字列は、任意の設定プロパティを参照するので、ファイルパスやファイルリストのようなデータは、冗長な記述を減らすためこの方法で指定されます。

任意のデータを設定オブジェクト内に格納することができ、必要とするタスクのプロパティと衝突することが無ければ、それは無視されます。これはJavaScriptでもあるため、JSONに限定されることは無く、ここでJavaScriptを使用することも可能です。もし、必要であればプログラムによって設定を生成することも可能です。

ほとんどのタスクと同様に、 grunt-contrib-uglify プラグインのuglifyタスクは、その構成内で同じ名前のプロパティが指定されることを期待します。ここでは、bannerオプションが、uglifyのターゲットとなる、単一のソースファイル(src)を単一の指定先(dest)に圧縮するbuildと一緒に指定されています。

// プロジェクト構成
grunt.initConfig({
  pkg: grunt.file.readJSON('package.json'),
  uglify: {
    options: {
      banner: '/*! <%= pkg.name %> <%= grunt.template.today("yyyy-mm-dd") %> */
'
    },
    build: {
      src: 'src/<%= pkg.name %>.js',
      dest: 'build/<%= pkg.name %>.min.js'
    }
  }
});

Gruntプラグインとタスクのロード

一般的によく使用される concat(連結)、 minify(圧縮)、 lint(構文チェック) などは、Gruntプラグインとして利用可能になりました。 package.jsonに依存関係としてプラグインが指定されていれば、 npm installによってインストールされ、Gruntfile内で次のように記述するだけで有効にすることが出来ます。

// "uglify"タスクを提供するプラグインのロード
grunt.loadNpmTasks('grunt-contrib-uglify');

grunt --helpコマンドは利用可能な全てのタスクを表示してくれます。

カスタムタスク

Gruntにdefaultタスクを定義することによって、デフォルトで単一または複数のタスクを実行させることが出来るようになります。下記の例では、コマンドライン上でgruntをタスクの指定無しに実行すると、uglifyタスクが実行されるようになります。機能的には、明確にgrunt uglifyと指定した場合と、grunt defaultは同じことをするようになります。多くのタスク(引数の有無に関わらず)は、配列で指定することも出来ます。

// デフォルトタスクの指定
grunt.registerTask('default', ['uglify']);

プロジェクトがGruntプラグインによって提供されていないタスクを必要とする場合、カスタムタスクをGruntfile内に定義することが可能です。例えば、このGruntfileでは、タスクの構成を必要としない完全なカスタムdefaultタスクを定義しています。

module.exports = function(grunt) {
  // 非常に基本的なデフォルトタスク
  grunt.registerTask('default', 'ログに記録します。', function() {
    grunt.log.write('ログに記録しています...').ok();
  });
};

プロジェクト固有のカスタムタスクは、Gruntfileに定義しなければいけないという事はありません。外部の.jsファイルに定義し、それを gruntgrunt.loadTasks によってロードすることが出来ます。

更に詳しく知るために

Gruntのインストールガイドでは、 gruntとgrunt-cliのプロダクトまたは開発中のバージョンを指定してのインストールについて、詳細な情報を載せてあります。
タスクの設定ガイドでは、タスク、ターゲット、オプションおよびテンプレート、グロブパターン、外部データのインポートの説明とともに、Gruntfile内のファイルを構成する方法の詳細な説明をしています。
タスクの作成ガイドでは、Gruntタスクのタイプの違いを一覧と、多くのタスクや設定のサンプルを紹介しています。
カスタムタスクやGruntプラグインについて更に多くの情報について知りたければ、デベロッパー(API)ドキュメントを確認してみてください。