プロジェクトスキャフォールディング

grunt-init

Grunt-initは、プロジェクトの作成を自動化するために使用されるスキャフォールディングツールです。現在の環境と、いくつかの質問への回答に基づいて、ディレクトリ構造全体を構築します。作成される正確なファイルと内容は、選択されたテンプレートと、質問への回答によって異なります。

注: このスタンドアロンユーティリティは、以前はGruntに「init」タスクとして組み込まれていました。この変更の詳細については、Gruntの0.3から0.4へのアップグレードガイドを参照してください。

インストール

grunt-initを使用するには、グローバルにインストールする必要があります。

npm install -g grunt-init

これにより、システムパスにgrunt-initコマンドが配置され、どこからでも実行できるようになります。

注: これを行うには、sudoを使用するか、コマンドシェルを管理者として実行する必要がある場合があります。

使い方

grunt-init --helpでプログラムのヘルプと利用可能なテンプレートのリストを取得します。
grunt-init TEMPLATEで利用可能なテンプレートに基づいてプロジェクトを作成します。
grunt-init /path/to/TEMPLATEで任意に配置されたテンプレートに基づいてプロジェクトを作成します。

ほとんどのテンプレートは現在のディレクトリにファイルを生成するため、既存のファイルを上書きしたくない場合は、最初に新しいディレクトリに変更してください。

テンプレートのインストール

テンプレートが~/.grunt-init/ディレクトリ（Windowsの場合は%USERPROFILE%\.grunt-init\）にインストールされると、grunt-initで使用できるようになります。gitを使用してテンプレートをそのディレクトリにクローンすることをお勧めします。たとえば、grunt-init-jqueryテンプレートは次のようにインストールできます。

git clone https://github.com/gruntjs/grunt-init-jquery.git ~/.grunt-init/jquery

注: テンプレートをローカルで「foobarbaz」として利用できるようにする場合は、クローン時に~/.grunt-init/foobarbazを指定できます。Grunt-initは、~/.grunt-init/ディレクトリ内に存在する実際のテンプレートディレクトリ名をそのまま使用します。

いくつかのgrunt-initテンプレートは公式に管理されています。

grunt-init-commonjs - Nodeunitユニットテストを含むcommonjsモジュールを作成します。（サンプル「生成済み」リポジトリ | 作成記録）
grunt-init-gruntfile - 基本的なGruntfileを作成します。（サンプル「生成済み」リポジトリ | 作成記録）
grunt-init-gruntplugin - Nodeunitユニットテストを含むGruntプラグインを作成します。（サンプル「生成済み」リポジトリ | 作成記録）
grunt-init-jquery - QUnitユニットテストを含むjQueryプラグインを作成します。（サンプル「生成済み」リポジトリ | 作成記録）
grunt-init-node - Nodeunitユニットテストを含むNode.jsモジュールを作成します。（サンプル「生成済み」リポジトリ | 作成記録）

カスタムテンプレート

カスタムテンプレートを作成して使用できます。テンプレートは、前述のテンプレートと同じ構造に従う必要があります。

my-templateという名前のサンプルテンプレートは、次の一般的なファイル構造に従います。

my-template/template.js - メインのテンプレートファイル。
my-template/rename.json - テンプレート固有のリネーム規則。テンプレートとして処理されます。
my-template/root/ - ターゲットの場所にコピーされるファイル。

これらのファイルが/path/to/my-templateに存在すると仮定すると、grunt-init /path/to/my-templateコマンドを使用してテンプレートを処理します。同じディレクトリに、名前が異なる複数のテンプレートが存在する場合があります。

さらに、このカスタムテンプレートを~/.grunt-init/ディレクトリ（Windowsの場合は%USERPROFILE%\.grunt-init\）に配置すると、grunt-init my-templateだけで自動的に使用できるようになります。

ファイルのコピー

テンプレートがinit.filesToCopyおよびinit.copyAndProcessメソッドを使用している限り、root/サブディレクトリ内のファイルは、initテンプレートの実行時に現在のディレクトリにコピーされます。

コピーされたすべてのファイルは、noProcessオプションが設定されていない限り、収集されたpropsデータオブジェクトに対して処理される{% %}テンプレートとして処理されます。例については、jqueryテンプレートを参照してください。

テンプレートファイルの名前変更または除外

rename.jsonは、sourcepathからdestpathへのリネームマッピングを記述します。sourcepathは、root/フォルダに対するコピーするファイルのパスである必要がありますが、destpathの値には{% %}テンプレートを含めることができ、宛先パスがどのように設定されるかを記述します。

destpathとしてfalseが指定された場合、ファイルはコピーされません。また、globパターンはsrcpathでサポートされています。

デフォルトのプロンプト回答の指定

各initプロンプトには、ハードコードされたデフォルト値があるか、現在の環境を見てデフォルト値を決定しようとします。特定のプロンプトのデフォルト値をオーバーライドする場合は、オプションのOS XまたはLinuxの~/.grunt-init/defaults.jsonファイル、またはWindowsの%USERPROFILE%\.grunt-init\defaults.jsonファイルでオーバーライドできます。

たとえば、デフォルトの名前とは少し異なる名前を使用したい、メールアドレスを除外したい、および自動的に作成者のURLを指定したいので、私のdefaults.jsonファイルは次のようになっています。

{
  "author_name": "\"Cowboy\" Ben Alman",
  "author_email": "none",
  "author_url": "http://benalman.com/"
}

注: すべての組み込みプロンプトが文書化されるまで、名前とデフォルト値はソースコードで確認できます。

initテンプレートの定義

exports.description

この短いテンプレートの説明は、ユーザーがgrunt initまたはgrunt-initを実行して利用可能なすべてのinitテンプレートのリストを表示するときに、テンプレート名とともに表示されます。

exports.description = descriptionString;

exports.notes

指定した場合、このオプションの拡張説明は、プロンプトが表示される前に表示されます。これは、命名規則、必須またはオプションのプロンプトなどを説明するのに役立つ良い場所です。

exports.notes = notesString;

exports.warnOn

このオプション（ただし推奨）のワイルドカードパターンまたはワイルドカードパターンの配列が一致する場合、Gruntは--forceでユーザーがオーバーライドできる警告で中止します。これは、initテンプレートが既存のファイルを上書きする可能性がある場合に非常に役立ちます。

exports.warnOn = wildcardPattern;

最も一般的な値は、任意のファイルまたはディレクトリに一致する'*'ですが、使用されるminimatchワイルドカードパターン構文では、非常に柔軟に対応できます。例えば

exports.warnOn = 'Gruntfile.js';    // Warn on a Gruntfile.js file.
exports.warnOn = '*.js';            // Warn on any .js file.
exports.warnOn = '*';               // Warn on any non-dotfile or non-dotdir.
exports.warnOn = '.*';              // Warn on any dotfile or dotdir.
exports.warnOn = '{.*,*}';          // Warn on any file or dir (dot or non-dot).
exports.warnOn = '!*/**';           // Warn on any file (ignoring dirs).
exports.warnOn = '*.{png,gif,jpg}'; // Warn on any image file.

// This is another way of writing the last example.
exports.warnOn = ['*.png', '*.gif', '*.jpg'];

exports.template

exportsプロパティはこの関数の外で定義されますが、実際のinitコードはすべて内部で指定されます。この関数には3つの引数が渡されます。grunt引数はgruntへの参照であり、すべてのgruntメソッドとライブラリが含まれています。init引数は、このinitテンプレートに固有のメソッドとプロパティを含むオブジェクトです。done引数は、initテンプレートの実行が完了したときに呼び出す必要がある関数です。

exports.template = function(grunt, init, done) {
  // See the "Inside an init template" section.
};

initテンプレート内

init.addLicenseFiles

適切な名前のライセンスファイルをファイルオブジェクトに追加します。

var files = {};
var licenses = ['MIT'];
init.addLicenseFiles(files, licenses);
// files === {'LICENSE-MIT': 'licenses/LICENSE-MIT'}

init.availableLicenses

利用可能なライセンスの配列を返します。

var licenses = init.availableLicenses();
// licenses === [ 'Apache-2.0', 'GPL-2.0', 'MIT', 'MPL-2.0' ]

init.copy

絶対または相対ソースパスと、オプションの相対宛先パスを指定して、ファイルをコピーし、オプションで渡されたコールバックを介して処理します。

init.copy(srcpath[, destpath], options)

init.copyAndProcess

渡されたオブジェクト内のすべてのファイルを反復処理し、ソースファイルを宛先にコピーし、コンテンツを処理します。

init.copyAndProcess(files, props[, options])

init.defaults

defaults.jsonからのユーザー指定のデフォルトinit値。

init.defaults

init.destpath

絶対宛先ファイルパス。

init.destpath()

init.expand

grunt.file.expandと同じ。

指定されたワイルドカードパターンに一致するすべてのファイルまたはディレクトリパスの一意の配列を返します。このメソッドは、コンマ区切りのワイルドカードパターンまたはワイルドカードパターンの配列を受け入れます。！で始まるパターンに一致するパスは、返される配列から除外されます。パターンは順番に処理されるため、包含と除外の順序が重要です。

init.expand([options, ] patterns)

init.filesToCopy

絶対ソースパスと相対宛先パスを含むコピーするファイルのオブジェクトを返し、rename.json（存在する場合）の規則に従って名前が変更（または省略）されます。

var files = init.filesToCopy(props);
/* files === { '.gitignore': 'template/root/.gitignore',
  '.jshintrc': 'template/root/.jshintrc',
  'Gruntfile.js': 'template/root/Gruntfile.js',
  'README.md': 'template/root/README.md',
  'test/test_test.js': 'template/root/test/name_test.js' } */

init.getFile

単一のタスクファイルパスを取得します。

init.getFile(filepath[, ...])

init.getTemplates

利用可能なすべてのテンプレートのオブジェクトを返します。

init.getTemplates()

init.initSearchDirs

initテンプレートを検索するディレクトリを初期化します。templateはテンプレートの場所です。~/.grunt-init/とgrunt-init内のコアinitタスクも含まれます。

init.initSearchDirs([filename])

init.process

入力を求めるプロンプトを開始するプロセスを開始します。

init.process(options, prompts, done)

init.process({}, [
  // Prompt for these values
  init.prompt('name'),
  init.prompt('description'),
  init.prompt('version')
], function(err, props) {
  // All finished, do something with the properties
});

init.prompt

ユーザーに値を求めます。

init.prompt(name[, default])

init.prompts

すべてのプロンプトのオブジェクト。

var prompts = init.prompts;

init.readDefaults

タスクファイル（存在する場合）からJSONデフォルトを読み取り、1つのデータオブジェクトにマージします。

init.readDefaults(filepath[, ...])

init.renames

テンプレートのリネーム規則。

var renames = init.renames;
// renames === { 'test/name_test.js': 'test/{%= name %}_test.js' }

init.searchDirs

テンプレートを検索するディレクトリの配列。

var dirs = init.searchDirs;
/* dirs === [ '/Users/shama/.grunt-init',
  '/usr/local/lib/node_modules/grunt-init/templates' ] */

init.srcpath

ファイル名のinitテンプレートパスを検索し、絶対パスを返します。

init.srcpath(filepath[, ...])

init.userDir

ユーザーのテンプレートディレクトリへの絶対パスを返します。

var dir = init.userDir();
// dir === '/Users/shama/.grunt-init'

init.writePackageJSON

宛先ディレクトリにpackage.jsonファイルを保存します。コールバックを使用して、プロパティを追加/削除/その他を行うために後処理できます。

init.writePackageJSON(filename, props[, callback])

組み込みプロンプト

author_email

package.json で使用する作者のメールアドレス。ユーザーの git 設定からデフォルト値を検出を試みます。

author_name

package.json および著作権表示で使用する作者のフルネーム。ユーザーの git 設定からデフォルト値を検出を試みます。

author_url

package.json で使用する作者のウェブサイトの公開 URL。

bin

プロジェクトルートからの相対パスで指定する CLI スクリプト。

bugs

プロジェクトの issue トラッカーの公開 URL。プロジェクトが GitHub リポジトリを持っている場合、デフォルトで GitHub issue トラッカーになります。

description

プロジェクトの説明。package.json および README ファイルで使用されます。

grunt_version

プロジェクトに必要な Grunt の有効なセマンティックバージョン範囲記述子。

homepage

プロジェクトのホームページの公開 URL。GitHub リポジトリの場合、デフォルトで GitHub URL になります。

jquery_version

jQuery プロジェクトの場合、プロジェクトに必要な jQuery のバージョン。有効なセマンティックバージョン範囲記述子である必要があります。

licenses

プロジェクトのライセンス。複数のライセンスはスペースで区切ります。組み込みのライセンスは、MIT、MPL-2.0、GPL-2.0、および Apache-2.0 です。デフォルトは MIT です。init.addLicenseFiles でカスタムライセンスを追加します。

main

プロジェクトの主要なエントリポイント。デフォルトは、lib フォルダー内のプロジェクト名です。

name

プロジェクトの名前。プロジェクトテンプレート全体で多用されます。デフォルトは現在の作業ディレクトリです。

node_version

プロジェクトに必要な Node.js のバージョン。有効なセマンティックバージョン範囲記述子である必要があります。

npm_test

プロジェクトでテストを実行するコマンド。デフォルトは grunt です。

repository

プロジェクトの git リポジトリ。デフォルトは、GitHub URL の推測値です。

title

人間が読めるプロジェクト名。デフォルトは、実際のプロジェクト名をより人間が読みやすいように変更したものです。

version

プロジェクトのバージョン。デフォルトは、最初の有効なセマンティックバージョンである 0.1.0 です。

ドキュメントにエラーを見つけましたか？ issue を提出してください。