はじめに

GruntとGruntプラグインは、npm（Node.jsのパッケージマネージャー）を介してインストールおよび管理されます。 Grunt 0.4.x は、安定版の Node.js バージョン >= 0.8.0 を必要とします。

Grunt を設定する前に、npm update -g npm を実行して、npm が最新であることを確認してください（特定のシステムでは sudo が必要な場合があります）。

Gruntを既にインストール済みで、簡単なリファレンスを探している場合は、Gruntfile の例とタスクの設定方法をご覧ください。

CLIのインストール

Grunt 0.3 を使用していますか？ Grunt 0.3 の注意事項をご覧ください。

使い始めるには、Gruntのコマンドラインインターフェース（CLI）をグローバルにインストールする必要があります。これを行うには、sudo（OSX、*nix、BSDなど）を使用するか、コマンドシェルを管理者として実行する必要がある場合があります（Windowsの場合）。

npm install -g grunt-cli

これにより、grunt コマンドがシステムパスに追加され、どのディレクトリからでも実行できるようになります。

grunt-cli をインストールしても、Gruntタスクランナーはインストールされません！ Grunt CLIの役割は単純です。Gruntfile の隣にインストールされているバージョンの Grunt を実行することです。これにより、同じマシンに複数のバージョンの Grunt を同時にインストールできます。

CLIの動作

grunt が実行されるたびに、Node.jsの require() システムを使用して、ローカルにインストールされている Grunt を探します。このため、プロジェクトの任意のサブフォルダーから grunt を実行できます。

ローカルにインストールされた Grunt が見つかった場合、CLI は Grunt ライブラリのローカルインストールを読み込み、Gruntfile からの設定を適用し、実行するように要求されたタスクを実行します。実際に何が起こっているのかを理解するには、コードを読んでください.

既存のGruntプロジェクトでの作業

Grunt CLI がインストールされていて、プロジェクトが既に package.json と Gruntfile で設定されていると仮定すると、Grunt での作業を開始するのは非常に簡単です。

プロジェクトのルートディレクトリに移動します。
npm install でプロジェクトの依存関係をインストールします。
grunt で Grunt を実行します。

本当に必要なのはこれだけです。インストールされている Grunt タスクは、grunt --help を実行することで一覧表示できますが、通常はプロジェクトのドキュメントから始めることをお勧めします。

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

典型的なセットアップでは、プロジェクトに2つのファイルを追加します。package.json と Gruntfile です。

package.json: このファイルは、npm が npm モジュールとして公開されているプロジェクトのメタデータを保存するために使用されます。このファイルに、プロジェクトに必要な grunt と Grunt プラグインを devDependencies としてリストします。

Gruntfile: このファイルは Gruntfile.js または Gruntfile.coffee という名前で、タスクの設定または定義、および Grunt プラグインの読み込みに使用されます。 このドキュメントで Gruntfile に言及している場合、それは Gruntfile.js または Gruntfile.coffee のいずれかのファイルを指しています。

package.json

package.json ファイルは、プロジェクトのルートディレクトリに Gruntfile と並んで配置し、プロジェクトソースと一緒にコミットする必要があります。 package.json ファイルと同じフォルダーで npm install を実行すると、そこにリストされている各依存関係の正しいバージョンがインストールされます。

プロジェクト用に package.json ファイルを作成するには、いくつかの方法があります。

ほとんどの grunt-init テンプレートは、プロジェクト固有の package.json ファイルを自動的に作成します。
npm init コマンドは、基本的な package.json ファイルを作成します。
以下の例から始めて、必要に応じてこの仕様に従って拡張してください。

{
  "name": "my-project-name",
  "version": "0.1.0",
  "devDependencies": {
    "grunt": "~0.4.5",
    "grunt-contrib-jshint": "~0.10.0",
    "grunt-contrib-nodeunit": "~0.4.1",
    "grunt-contrib-uglify": "~0.5.0"
  }
}

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

既存の package.json に Grunt と gruntプラグインを追加する最も簡単な方法は、npm install <module> --save-dev コマンドを使用することです。これにより、<module> がローカルにインストールされるだけでなく、チルダバージョン範囲を使用して、devDependencies セクションに自動的に追加されます。

たとえば、これによりプロジェクトフォルダーに最新バージョンの Grunt がインストールされ、devDependencies に追加されます。

npm install grunt --save-dev

gruntプラグインやその他のノードモジュールについても同様です。次の例に示すように、JSHintタスクモジュールをインストールします。

npm install grunt-contrib-jshint --save-dev

プロジェクトにインストールして使用できる現在の gruntプラグインは、プラグインページで確認してください。

完了したら、更新された package.json ファイルをプロジェクトと一緒にコミットしてください！

Gruntfile

Gruntfile.js または Gruntfile.coffee ファイルは、プロジェクトのルートディレクトリに package.json ファイルと並んで配置する有効な JavaScript または CoffeeScript ファイルであり、プロジェクトソースと一緒にコミットする必要があります。

Gruntfile は、以下の部分で構成されています。

「ラッパー」関数
プロジェクトとタスクの設定
Grunt プラグインとタスクの読み込み
カスタムタスク

Gruntfileの例

次の Gruntfile では、プロジェクトのメタデータがプロジェクトの package.json ファイルから Grunt 設定にインポートされ、grunt-contrib-uglify プラグインの uglify タスクが、ソースファイルを縮小し、そのメタデータを使用してバナーコメントを動的に生成するように設定されています。コマンドラインで grunt を実行すると、uglify タスクがデフォルトで実行されます。

module.exports = function(grunt) {

  // Project configuration.
  grunt.initConfig({
    pkg: grunt.file.readJSON('package.json'),
    uglify: {
      options: {
        banner: '/*! <%= pkg.name %> <%= grunt.template.today("yyyy-mm-dd") %> */\n'
      },
      build: {
        src: 'src/<%= pkg.name %>.js',
        dest: 'build/<%= pkg.name %>.min.js'
      }
    }
  });

  // Load the plugin that provides the "uglify" task.
  grunt.loadNpmTasks('grunt-contrib-uglify');

  // Default task(s).
  grunt.registerTask('default', ['uglify']);

};

Gruntfile 全体を理解したので、今度はその構成要素を見てみましょう。

「ラッパー」関数

すべての Gruntfile（および gruntプラグイン）はこの基本的な形式を使用しており、すべての Grunt コードはこの関数内に指定する必要があります。

module.exports = function(grunt) {
  // Do grunt-related things in here
};

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

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

この例では、grunt.file.readJSON('package.json') は package.json に保存されている JSON メタデータを grunt 設定にインポートします。 <% %> テンプレート文字列は任意の設定プロパティを参照できるため、ファイルパスやファイルリストなどの設定データをこの方法で指定して、繰り返しを減らすことができます。

設定オブジェクト内に任意のデータを保存でき、タスクに必要なプロパティと競合しない限り、無視されます。また、これは JavaScript なので、JSON に限定されません。有効な JS をここで使用できます。必要に応じて、プログラムで設定を生成することもできます。

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

// Project configuration.
grunt.initConfig({
  pkg: grunt.file.readJSON('package.json'),
  uglify: {
    options: {
      banner: '/*! <%= pkg.name %> <%= grunt.template.today("yyyy-mm-dd") %> */\n'
    },
    build: {
      src: 'src/<%= pkg.name %>.js',
      dest: 'build/<%= pkg.name %>.min.js'
    }
  }
});

Gruntプラグインとタスクの読み込み

連結、縮小、リントなど、多くの一般的に使用されるタスクは、gruntプラグインとして利用できます。プラグインが package.json に依存関係として指定され、npm install 経由でインストールされている限り、簡単なコマンドで Gruntfile 内で有効にすることができます。

// Load the plugin that provides the "uglify" task.
grunt.loadNpmTasks('grunt-contrib-uglify');

注： grunt --help コマンドは、使用可能なすべてのタスクをリストします。

カスタムタスク

default タスクを定義することで、Grunt がデフォルトで1つ以上のタスクを実行するように設定できます。次の例では、コマンドラインでタスクを指定せずに grunt を実行すると、uglify タスクが実行されます。これは、明示的に grunt uglify を実行すること、さらには grunt default を実行することと機能的に同じです。配列には、任意の数のタスク（引数付きまたは引数なし）を指定できます。

// Default task(s).
grunt.registerTask('default', ['uglify']);

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

module.exports = function(grunt) {

  // A very basic default task.
  grunt.registerTask('default', 'Log some stuff.', function() {
    grunt.log.write('Logging some stuff...').ok();
  });

};

プロジェクト固有のカスタムタスクは、Gruntfile に定義する必要はありません。外部 .js ファイルに定義し、grunt.loadTasks メソッドを介してロードできます。

参考文献

gruntのインストールガイドには、特定の、本番または開発中のバージョンの Grunt と grunt-cli のインストールに関する詳細な情報があります。
タスクの設定ガイドには、Gruntfile 内でタスク、ターゲット、オプション、およびファイルを設定する方法の詳細な説明と、テンプレート、グロビングパターン、および外部データのインポートの説明があります。
タスクの作成ガイドには、Gruntタスクの種類の違いがリストされており、多数のサンプルタスクと設定が示されています。
カスタムタスクまたは Grunt プラグインの作成の詳細については、開発者向けドキュメントをご覧ください。

ドキュメントに誤りを見つけましたか？問題を報告してください.