0.3 から 0.4 へのアップグレード

Grunt に精通している場合でも、新しいはじめにガイドを読むことをお勧めします。

Grunt は現在、grunt、grunt-cli、grunt-initの3つの部分に分割されています。

npm モジュールgruntは、プロジェクトにローカルにインストールする必要があります。これには、タスクの実行、プラグインの読み込みなどを行うためのコードとロジックが含まれています。
npm モジュールgrunt-cliはグローバルにインストールする必要があります。これにより、gruntコマンドがPATHに追加され、どこからでも実行できるようになります。それ自体は何も行いません。その役割は、バージョンに関係なく、プロジェクトにローカルにインストールされているGruntを読み込んで実行することです。この変更の詳細については、npm 1.0: グローバルとローカルのインストールをお読みください。
initタスクは、独自のnpmモジュールgrunt-initに分割されました。これは、npm install -g grunt-initでグローバルにインストールし、grunt-initコマンドで実行する必要があります。今後数ヶ月以内に、Yeomanがgrunt-initを完全に置き換える予定です。詳細については、grunt-init プロジェクトページを参照してください。

Grunt 0.3 の注意事項

Grunt 0.3 からアップグレードする場合は、グローバルgruntをアンインストールしてください。

npm uninstall -g grunt

"Gruntfile"セクションに示されているものとは、0.3.xではプラグイン名とタスク設定オプションが異なる場合があります。

このファイルは、Gruntの0.3.xバージョンではgrunt.jsという名前でした。

既存のタスクとプラグイン

すべてのgrunt-contrib-*シリーズプラグインはGrunt 0.4に対応しています。ただし、Grunt 0.3用に作成されたサードパーティ製プラグインは、更新されるまで0.4で動作しなくなる可能性が非常に高くなります。この問題が迅速に解決されるよう、プラグイン開発者と積極的に協力しています。

今後のGruntリリースでは、アーキテクチャの分離に重点を置くことで、プラグインが将来のアップデートの影響を受けないようにします。

要件

Gruntは現在、Node.jsバージョン>= 0.8.0が必要です。

Gruntfile

"Gruntfile"はgrunt.jsからGruntfile.jsに変更されました。
プロジェクトのGruntfile.coffee、Gruntfile、または*.coffeeタスクファイルでCoffeeScriptがサポートされています（JSへのトランスパイルは自動的に行われます）。

詳細については、はじめにガイドの"Gruntfile"セクションを参照してください。

コアタスクはGruntプラグインになりました

Grunt 0.3に含まれていた8つのコアタスクは、個別のGruntプラグインになりました。それぞれが個別のnpmモジュールであり、「Gruntプラグインとタスクの読み込み」セクションのはじめにガイドに従ってプラグインとしてインストールする必要があります。

concat → grunt-contrib-concat プラグイン
init → 独立したgrunt-initユーティリティ
lint → grunt-contrib-jshint プラグイン
min → grunt-contrib-uglify プラグイン
qunit → grunt-contrib-qunit プラグイン
server → grunt-contrib-connect プラグイン
test → grunt-contrib-nodeunit プラグイン
watch → grunt-contrib-watch プラグイン

一部のタスク名とオプションが変更されています。最新の構成の詳細については、上記の各プラグインのドキュメントを参照してください。

設定

Grunt 0.4タスクの設定形式は標準化され、大幅に強化されました。詳細については、タスクの設定ガイドと個々のプラグインのドキュメントを参照してください。

ファイルグローブ（ワイルドカード）パターンは、一致するファイルを排除するために否定できるようになりました。
タスクは標準のoptionsオブジェクトをサポートするようになりました。
タスクは標準のfilesオブジェクトをサポートするようになりました。

<% %>スタイルのテンプレート文字列は、Gruntfile内の構成データとして指定された場合、自動的に展開されます。詳細については、grunt.templateドキュメントを参照してください。

ディレクティブは削除されましたが、その機能は保持されています。これらの置換を行うことができます。

'<config:prop.subprop>' → '<%= prop.subprop %>'
'<json:file.json>' → grunt.file.readJSON('file.json')
'<file_template:file.js>' → grunt.template.process(grunt.file.read('file.js'))

'<banner>'または'<banner:prop.subprop>'を使用してファイルリストでバナーを指定する代わりに、grunt-contrib-concatとgrunt-contrib-uglifyの各プラグインにはbannerオプションがあります。

'<file_strip_banner:file.js>'を使用して個別にバナーを削除する代わりに、grunt-contrib-concatとgrunt-contrib-uglifyの各プラグインには、バナーを削除/保持するためのオプションがあります。

エイリアスタスクの変更

エイリアスタスクを指定する場合、実行するタスクのリストは配列として指定する必要があります。

// v0.3.x (old format)
grunt.registerTask('default', 'jshint nodeunit concat');
// v0.4.x (new format)
grunt.registerTask('default', ['jshint', 'nodeunit', 'concat']);

タスク引数にスペースを含めることができるようになりました

前述のエイリアスタスクの変更（タスクリストは配列として指定する必要がある）により、これが可能になりました。コマンドラインで指定する際には、スペースを含むタスク引数を引用符で囲んでください。これにより、正しく解析できます。

grunt my-task:argument-without-spaces "other-task:argument with spaces"

文字エンコーディング

file.defaultEncodingメソッドが追加され、文字エンコーディングが正規化されました。すべてのgrunt.fileメソッドは、指定されたエンコーディングをサポートするように更新されています。

ヘルパー

Gruntのヘルパーシステムは、ノードのrequireに置き換えられました。Gruntプラグイン間で機能を共有する方法の簡潔な例については、grunt-lib-legacyhelpersを参照してください。プラグイン開発者は、プラグインのアップグレードを推奨します。

API

Grunt APIは、0.3から0.4への変更で大幅に変更されました。

grunt
- grunt.registerHelperメソッドとgrunt.renameHelperメソッドが削除されました。
grunt.config
- config.getメソッドは、<% %>テンプレートを再帰的に自動的に展開するように変更されました。
- config.getRawメソッドが追加されました。これは、生の（展開されていない）構成データを取得します。
- config.processメソッドは、構成から取得されたかのように値を処理し、テンプレートを再帰的に展開するように変更されました。このメソッドはconfig.get内部で内部的に呼び出されますが、config.getRaw内部では呼び出されません。
grunt.eventが追加され、タスクがイベントを発行できるようになりました。
grunt.fail
- --no-colorオプションが指定されている場合、ビープ音を出しません。
- fail.code終了コードマップが追加されました。
- fail.warnAlternateメソッドが削除されました。
grunt.file
- タスクは、~/.grunt/tasks/ディレクトリから自動的にロードされなくなりました（プロジェクトにローカルにインストールしてください！）。
- すべてのgrunt.fileメソッドで文字エンコーディングを正規化するためのfile.defaultEncodingメソッドが追加されました。
- file.deleteメソッドが追加されました。
- 比較的分かりやすいfile.exists、file.isDir、file.isFile、file.isLink、file.isPathCwd、file.isPathInCwd、file.doesPathContain、file.arePathsEquivalentテストメソッドが追加されました。
- ワイルドカードパターンとファイルパスの照合を容易にするfile.matchメソッドとfile.isMatchメソッドが追加されました。
- 1対1のsrc-destファイルマッピングの生成に使用するfile.expandMappingメソッドが追加されました。
- file.readYAMLメソッドが追加されました。
- file.findupは、findup-syncモジュールを使用するように変更されました。
- file.globは、globモジュールを使用するように変更されました。
- minimatchモジュールを公開するfile.minimatchが追加されました。
- file.userDirメソッドが削除されました（grunt-initに移動されました）。
- file.clearRequireCacheメソッドが削除されました。
- file.expandFilesメソッドとfile.expandDirsメソッドが削除されました。代わりにfile.expandのfilterオプションを使用してください。
- file.expandFileURLsメソッドが削除されました。ファイルが指定されるべき場所にURLを指定しないでください（例：qunitタスクは現在urlsオプションを許可しています）。
grunt.task
- task.registerTaskとtask.registerMultiTaskの両方で登録されたタスクは、this.optionsメソッドを取得します。
- マルチタスクfilesオブジェクトをthis.fileプロパティに正規化するのを容易にするtask.normalizeMultiTaskFilesメソッドが追加されました。
- task.registerHelperメソッドとtask.renameHelperメソッドが削除されました。
- task.searchDirsプロパティが削除されました。
- task.expand、task.expandDirs、task.expandFiles、task.getFile、task.readDefaultsメソッドが削除されました（grunt-initに移動されました）。
grunt.packageは、gruntのpackage.jsonに格納されているメタデータを表します。
grunt.versionは、Gruntの現在のバージョンを文字列として表します。
grunt.template
- 新しいテンプレートデリミタを追加するtemplate.addDelimitersメソッドを追加しました。
- テンプレートデリミタを選択するtemplate.setDelimitersメソッドを追加しました。
- initとuserテンプレートデリミタは削除されましたが、必要であればtemplate.addDelimitersで再び追加できます（grunt-initはこの機能を使用して{% %}テンプレートデリミタを有効にしています）。
grunt.utilが、削除されたgrunt.utilsに置き換わります。
- util._をLo-Dashを使用するように変更しました。
- util.callbackifyメソッドを追加しました。
- util.spawnメソッドを大幅に改良し、より一貫性のある引数をコールバックに渡すように変更しました。

タスク/プラグイン作成者

プラグイン作成者は、Gruntプラグインのどのバージョン番号がGrunt 0.3との互換性を損なうかを、リポジトリのREADMEに明確に示してください。

タスク

マルチタスク
- filesオブジェクト内で、ターゲットごとに複数のsrc-destファイルマッピングを指定できるようになりました（オプションです）。
this.files / grunt.task.current.files
- this.filesプロパティは、マルチタスクで繰り返し処理されるsrc-destファイルマッピングオブジェクトの配列です。常に配列であり、最も一般的な使用方法が単一ファイルの指定であっても、常に繰り返し処理する必要があります。
- 各src-destファイルマッピングオブジェクトには、srcプロパティとdestプロパティがあります（ユーザーが指定したものによっては、他にもプロパティがあります）。srcプロパティは、ユーザーが指定したglobパターンから既に展開されています。
this.filesSrc / grunt.task.current.filesSrc
- this.filesSrcプロパティは、指定されたすべてのsrcプロパティによって一致したすべてのファイルの、重複を除いた配列です。読み取り専用のタスクに役立ちます。
this.options / grunt.task.current.options
- タスク内で、this.optionsメソッドを使用してオプションを正規化できます。タスク内では、次のようにオプションのデフォルト値を指定できます。var options = this.options({option: 'defaultvalue', ...});

プラグイン

Grunt 0.4互換プラグイン用の更新されたgruntpluginテンプレートが作成され、スタンドアロンのgrunt-initで利用できます。

トラブルシューティング

以前Grunt 0.4またはgrunt-contribプラグインの開発版をインストールしていた場合は、npm cache cleanでnpmキャッシュを最初にフラッシュして、Gruntとgrunt-contribプラグインの最終版を取得していることを確認してください。

ドキュメントに誤りを見つけましたか？問題を報告する。