Laravel master アセットのコンパイル(Laravel Elixir)

イントロダクションIntroduction

Laravel Elixir（エリクサー：万能薬）は、Laravelアプリケーションのための基本的なGulpタスクを定義しており、美しくスラスラかけるAPIを提供しています。ElixirはSassやWebpackのような、一般的なCSSとJavascriptプリプロセッサーをサポートしています。メソッドのチェーンを使用し、Elixirでアセットパイプラインを流暢に定義できます。例を見てください。Laravel Elixir provides a clean, fluent API for defining basic Gulp[http://gulpjs.com] tasks for your Laravel application. Elixir supports common CSS and JavaScript pre-processors like Sass[http://sass-lang.com] and Webpack[https://webpack.github.io/]. Using method chaining, Elixir allows you to fluently define your asset pipeline. For example:

elixir(function(mix) {
    mix.sass('app.scss')
       .webpack('app.js');
});

Gulpやアセットのコンパイルを始めようとして、混乱と圧倒を感じているならLaravel Elixirを気に入ってもらえるでしょう。しかし、アプリケーションの開発時に必要だというわけではありません。どんなアセットパイプラインツールを使用してもかまいませんし、使わなくても良いのです。If you've ever been confused and overwhelmed about getting started with Gulp and asset compilation, you will love Laravel Elixir. However, you are not required to use it while developing your application. You are free to use any asset pipeline tool you wish, or even none at all.

インストールと準備Installation & Setup

NodeのインストールInstalling Node

Elixirを始める前、最初にNode.jsとNPMを開発機にインストール済みであることを確認してください。Before triggering Elixir, you must first ensure that Node.js and NPM are installed on your machine.

node -v
npm -v

Laravel Homesteadならデフォルトのままでも必要なものが全部そろっています。しかし、Vagrantを使っていなくても、ダウンロードページを読めば、NodeとNPMは簡単にインストールできます。By default, Laravel Homestead includes everything you need; however, if you aren't using Vagrant, then you can easily install the latest version of Node and NPM using simple graphical installers from their download page[http://nodejs.org/en/download/].

GulpGulp

次にGulpをグローバルNPMパッケージとして取得します。Next, you'll need to pull in Gulp[http://gulpjs.com] as a global NPM package:

npm install --global gulp-cli

Laravel ElixirLaravel Elixir

残っているステップはElixirのインストールだけです。新しくLaravelをインストールすると、ルートディレクトリにpackage.jsonがあることに気づくでしょう。PHPの代わりにNodeの依存パッケージが定義されている所が異なりますが、composer.jsonファイルと同じようなものだと考えてください。以下のコマンドで、依存パッケージをインストールしてください。The only remaining step is to install Laravel Elixir. Within a fresh installation of Laravel, you'll find a package.json file in the root of your directory structure. The default package.json file includes Elixir and the Webpack JavaScript module bundler. Think of this like your composer.json file, except it defines Node dependencies instead of PHP. You may install the dependencies it references by running:

npm install

Windowsシステムで開発を行っている場合、もしくはWindowsをホストとして仮想マシンを実行しているときは、--no-bin-linksを有効にしてnpm installコマンドを実行してください。If you are developing on a Windows system or you are running your VM on a Windows host system, you may need to run the npm install command with the --no-bin-links switch enabled:

npm install --no-bin-links

Elixirの実行Running Elixir

ElixirはGulp上に構築されていますので、端末でgulpコマンドを実行するだけでElixirタスクを走らせることができます。コマンドに--productionフラッグを付けることで、ElixirにCSSとJavaScriptファイルを圧縮するように指示できます。Elixir is built on top of Gulp[http://gulpjs.com], so to run your Elixir tasks you only need to run the gulp command in your terminal. Adding the --production flag to the command will instruct Elixir to minify your CSS and JavaScript files:

// 全タスク実行
gulp

// 全タスクを実行し、全CSSとJavaScriptを圧縮
gulp --production

コマンド実行中は、その時点のイベントのサマリーを示す、きれいにフォーマットされた一覧が表示されます。Upon running this command, you'll see a nicely formatted table that displays a summary of the events that just took place.

アセットの変更監視Watching Assets For Changes

gulp watchコマンドは、端末で動き続け、アセットの変更を監視し続けます。watchコマンド実行中にアセットを更新すれば、Gulpは自動的に再コンパイルします。The gulp watch command will continue running in your terminal and watch your assets for any changes. Gulp will automatically recompile your assets if you modify them while the watch command is running:

gulp watch

スタイルシート操作Working With Stylesheets

プロジェクトルートにあるgulpfile.jsファイルに全Elixirタスクを構成します。Elixirタスクはアセットをどのようにコンパイルするか実際に定義するためにチェーンでつなげます。The gulpfile.js file in your project's root directory contains all of your Elixir tasks. Elixir tasks can be chained together to define exactly how your assets should be compiled.

LessLess

LessをCSSへコンパイルするにはlessメソッドを使用します。lessメソッドはLessファイルがresources/assets/lessに保存されていることを想定しています。コンパイルされたCSSはデフォルトでpublic/css/app.cssへ保存します。The less method may be used to compile Less[http://lesscss.org/] into CSS. The less method assumes that your Less files are stored in resources/assets/less. By default, the task will place the compiled CSS for this example in public/css/app.css:

elixir(function(mix) {
    mix.less('app.less');
});

さらに複数のLessファイルを一つのCSSファイルへ結合できます。この結果のCSSもpublic/css/app.cssとして保存します。You may also combine multiple Less files into a single CSS file. Again, the resulting CSS will be placed in public/css/app.css:

elixir(function(mix) {
    mix.less([
        'app.less',
        'controllers.less'
    ]);
});

コンパイル済みのCSSの出力先をカスタマイズしたい場合は、lessメソッドに第２引数で指定します。If you wish to customize the output location of the compiled CSS, you may pass a second argument to the less method:

elixir(function(mix) {
    mix.less('app.less', 'public/stylesheets');
});

// 出力ファイル名を指定する…
elixir(function(mix) {
    mix.less('app.less', 'public/stylesheets/style.css');
});

SassSass

sassメソッドはSassをCSSへコンパイルします。Sassファイルはresources/assets/sassへ保存されていると想定します。このメソッドは次のように使用します。The sass method allows you to compile Sass[http://sass-lang.com/] into CSS. Assuming your Sass files are stored at resources/assets/sass, you may use the method like so:

elixir(function(mix) {
    mix.sass('app.scss');
});

lessメソッドと同様に複数のSassファイルを一つのCSSファイルへまとめることができ、結果のCSSを出力するディレクトリもカスタマイズできます。Again, like the less method, you may compile multiple Sass files into a single CSS file, and even customize the output directory of the resulting CSS:

elixir(function(mix) {
    mix.sass([
        'app.scss',
        'controllers.scss'
    ], 'public/assets/css');
});

パスのカスタマイズCustom Paths

Laravelデフォルトのアセットディレクトリを使用することをお勧めしますが、異なるベースディレクトリを使う必要があるなら、ファイルパスを./から初めて指定してください。この指定により、Laravelへデフォルトのベースディレクトリの代わりに、プロジェクトルートを指示できます。While it's recommended that you use Laravel's default asset directories, if you require a different base directory, you may begin any file path with ./. This instructs Elixir to begin at the project root, rather than using the default base directory.

たとえば、app/assets/sass/app.scssファイルをコンパイルし、結果をpublic/css/app.cssとして出力したければ、sassメソッドを以下のように呼び出します。For example, to compile a file located at app/assets/sass/app.scss and output the results to public/css/app.css, you would make the following call to the sass method:

elixir(function(mix) {
    mix.sass('./app/assets/sass/app.scss');
});

StylusStylus

StylusをCSSへ変換するにはstylusメソッドを使います。Stylusファイルは、resources/assets/stylusへ設置されると想定しています。以下のようにメソッドを呼び出します。The stylus method may be used to compile Stylus[http://stylus-lang.com/] into CSS. Assuming that your Stylus files are stored in resources/assets/stylus, you may call the method like so:

elixir(function(mix) {
    mix.stylus('app.styl');
});

lightbulb">Tip!! このメソッドの使用方法はmix.less()やmix.sass()と同じです。{tip} This method's signature is identical to both mix.less() and mix.sass().

通常のCSSPlain CSS

通常のCSSスタイルシートを一つのファイルに結合したい場合は、stylesメソッドを使います。このメソッドに渡すパスはresources/assets/cssからの相対位置で、結果のCSSはpublic/css/all.cssに保存されます。If you would just like to combine some plain CSS stylesheets into a single file, you may use the styles method. Paths passed to this method are relative to the resources/assets/css directory and the resulting CSS will be placed in public/css/all.css:

elixir(function(mix) {
    mix.styles([
        'normalize.css',
        'main.css'
    ]);
});

stylesメソッドの第２引数で、結果を出力するカスタムディレクトリかファイルを指定することも可能です。You may also instruct Elixir to write the resulting file to a custom directory or file by passing a second argument to the styles method:

elixir(function(mix) {
    mix.styles([
        'normalize.css',
        'main.css'
    ], 'public/assets/css/site.css');
});

ソースマップSource Maps

Elixirではソースマップは、デフォルトで有効になっており、コンパイルしたアセットを利用時に、ブラウザの開発者ツールでよりわかりやすいデバッグ情報が確認できます。コンパイルされた各ファイルごとに、同じディレクトリ中に同名の*.css.mapか*.js.mapファイルが存在しているのが見つかるでしょう。In Elixir, source maps are enabled by default and provide better debugging information to your browser's developer tools when using compiled assets. For each relevant file that is compiled, you will find a companion *.css.map or *.js.map file in the same directory.

アプリケーションのソースマップを生成したくなければ、sourcemaps設定オプションで無効にしてください。If you do not want source maps generated for your application, you may disable them using the sourcemaps configuration option:

elixir.config.sourcemaps = false;

elixir(function(mix) {
    mix.sass('app.scss');
});

スクリプト操作Working With Scripts

ElixirはECMAScript 2015のコンパイル、モジュールのバンドル、圧縮、シンプルなJavaScriptファイルの結合など、JavaScript操作を手助けする多くの機能を提供しています。Elixir provides several features to help you work with your JavaScript files, such as compiling ECMAScript 2015, module bundling, minification, and simply concatenating plain JavaScript files.

ES2015をモジュールで書く場合、WebpackかRollupを選択できます。両ツールについてよく知らなくても、心配ありません。Elixirが裏の面倒な仕事を一手に引き受けます。デフォルトではLaravelのgulpfileはwebpackをJavaScriptのコンパイルに使っていますが、好きなモジュールバンドラーを自由に使用できます。When writing ES2015 with modules, you have your choice between Webpack[http://webpack.github.io] and Rollup[http://rollupjs.org/]. If these tools are foreign to you, don't worry, Elixir will handle all of the hard work behind the scenes. By default, the Laravel gulpfile uses webpack to compile Javascript, but you are free to use any module bundler you like.

WebpackWebpack

webpackメソッドは、ECMAScript 2015をプレーンなJavaScriptへコンパイルし、ファイル結合するために使用します。この関数はresources/assets/jsディレクトリからの相対パスを引数に取り、public/js上へ結合済みの単一ファイルを生成します。The webpack method may be used to compile and bundle ECMAScript 2015[https://babeljs.io/docs/learn-es2015/] into plain JavaScript. This function accepts a file path relative to the resources/assets/js directory and generates a single bundled file in the public/js directory:

elixir(function(mix) {
    mix.webpack('app.js');
});

他の出力先やベースディレクトリを選ぶには、希望するパスを先頭の.に続け、アプリケーションルートからの相対パスとして指定してください。たとえば、app/assets/js/app.jsをpublic/dist/app.jsへコンパイルするには：To choose a different output or base directory, simply specify your desired paths with a leading .. Then you may specify the paths relative to the root of your application. For example, to compile app/assets/js/app.js to public/dist/app.js:

elixir(function(mix) {
    mix.webpack(
        './app/assets/js/app.js',
        './public/dist'
    );
});

Webpackの機能をより活用したい場合は、プロジェクトルートのwebpack.config.jsファイルを用意してください。Elixirが読み込み、ビルドプロセスへその設定を組み込みます。If you'd like to leverage more of Webpack's functionality, Elixir will read any webpack.config.js file that is in your project root and factor its configuration[https://webpack.github.io/docs/configuration.html] into the build process.

RollupRollup

Webpackと同様、RollupもES2015の次世代バンドラーです。rollup関数はresources/assets/jsディレクトリからの相対パスの配列を引数に取り、public/jsディレクトリへ単一ファイルを生成します。Similar to Webpack, Rollup is a next-generation bundler for ES2015. This function accepts an array of files relative to the resources/assets/js directory, and generates a single file in the public/js directory:

elixir(function(mix) {
    mix.rollup('app.js');
});

webpackメソッドと同様に、入出力ファイルの場所をrollupメソッドに指定し、カスタマイズできます。Like the webpack method, you may customize the location of the input and output files given to the rollup method:

elixir(function(mix) {
    mix.rollup(
        './resources/assets/js/app.js',
        './public/dist'
    );
});

JavaScriptScripts

複数のJavaScriptファイルを結合し、単一ファイルにしたい場合は、scriptsメソッドを使います。自動的にソースマップを生成し、結合し、圧縮します。If you have multiple JavaScript files that you would like to combine into a single file, you may use the scripts method, which provides automatic source maps, concatenation, and minification.

scriptsメソッドは全パスをresources/assets/jsからの相対位置であると想定し、結果をデフォルトでpublic/js/all.jsに置きます。The scripts method assumes all paths are relative to the resources/assets/js directory, and will place the resulting JavaScript in public/js/all.js by default:

elixir(function(mix) {
    mix.scripts([
        'order.js',
        'forum.js'
    ]);
});

複数のスクリプトを異なったファイルに結合したい場合は、scriptsメソッドを複数回呼び出してください。それぞれの結合の結果を出力するファイル名は、第２引数で指定します。If you need to concatenate multiple sets of scripts into different files, you may make multiple calls to the scripts method. The second argument given to the method determines the resulting file name for each concatenation:

elixir(function(mix) {
    mix.scripts(['app.js', 'controllers.js'], 'public/js/app.js')
       .scripts(['forum.js', 'threads.js'], 'public/js/forum.js');
});

指定したディレクトリの全スクリプトを結合するには、scriptsInメソッドを使います。結果のJavaScriptはpublic/js/all.jsに設置されます。If you need to combine all of the scripts in a given directory, you may use the scriptsIn method. The resulting JavaScript will be placed in public/js/all.js:

elixir(function(mix) {
    mix.scriptsIn('public/js/some/directory');
});

lightbulb">Tip!! jQueryのように既にミニファイされている、複数のベンダーファイルを結合したい場合は、代わりにmix.combine()の使用を考慮してください。このメソッドはファイルを結合しますが、ソースマップ生成とミニファイを行いません。結果として、コンパイル時間はドラマティックに改善されます。{tip} If you intend to concatenate multiple pre-minified vendor libraries, such as jQuery, instead consider using mix.combine(). This will combine the files, while omitting the source map and minification steps. As a result, compile times will drastically improve.

ファイルとディレクトリのコピーCopying Files & Directories

copyメソッドはファイルとディレクトリを新しい場所へコピーするために使用できます。全操作はプロジェクトルートディレクトリからの相対位置で指定します。The copy method may be used to copy files and directories to new locations. All operations are relative to the project's root directory:

elixir(function(mix) {
	mix.copy('vendor/foo/bar.css', 'public/css/bar.css');
});

バージョン付け／キャッシュ破壊Versioning / Cache Busting

多くの開発者がコンパイルしたアセットにタイムスタンプや一意なトークンをサフィックスとして付加し、保存されている古いコードの代わりに真新しいアセットを強制的にロードさせています。Elixirはこれをversionメソッドで処理します。Many developers suffix their compiled assets with a timestamp or unique token to force browsers to load the fresh assets instead of serving stale copies of the code. Elixir can handle this for you using the version method.

versionメソッドはpublicディレクトリからの相対パスファイル名を受け取り、ファイル名に一意なハッシュを付けることでキャッシュを破壊します。たとえば生成されたファイル名はall-16d570a7.cssのような名前になります。The version method accepts a file name relative to the public directory, and will append a unique hash to the filename, allowing for cache-busting. For example, the generated file name will look something like: all-16d570a7.css:

elixir(function(mix) {
    mix.version('css/all.css');
});

バージョンが付いたファイルを生成した後、ビューの中からLaravelのグローバルelixir関数を使い、ハッシュが付いたアセットをロードすることができます。elixir関数はハッシュをつけたファイル名を自動的に決定します。After generating the versioned file, you may use Laravel's global elixir helper within your views[/docs/{{version}}/views] to load the appropriately hashed asset. The elixir function will automatically determine the current name of the hashed file:

<link rel="stylesheet" href="{{ elixir('css/all.css') }}">

複数ファイルのバージョン付けVersioning Multiple Files

versionメソッドへ配列で複数ファイルを渡すこともできます。You may pass an array to the version method to version multiple files:

elixir(function(mix) {
    mix.version(['css/all.css', 'js/app.js']);
});

ファイルにバージョンが付けられたら、elixirヘルパ関数でハッシュが付いた実際のファイルへリンクを生成することができます。elixirヘルパ関数にはハッシュをつけていないファイル名を渡す必要があることを覚えておきましょう。Once the files have been versioned, you may use the elixir helper function to generate links to the proper hashed files. Remember, you only need to pass the name of the un-hashed file to the elixir helper function. The helper will use the un-hashed name to determine the current hashed version of the file:

<link rel="stylesheet" href="{{ elixir('css/all.css') }}">

<script src="{{ elixir('js/app.js') }}"></script>

BrowserSyncBrowserSync

browserSyncメソッドは、アプリケーションのローカルURLを含むproxy属性を持つ、JavaScriptオプジェクトを引数に取ります。その後、gulp watchを実行すれば、ポート3000（http://project.dev:3000）でWebアプリケーションへアクセスでき、ブラウザ自動同期を楽しめます。BrowserSync automatically refreshes your web browser after you make changes to your assets. The browserSync method accepts a JavaScript object with a proxy attribute containing the local URL for your application. Then, once you run gulp watch you may access your web application using port 3000 (http://project.dev:3000) to enjoy browser syncing:

elixir(function(mix) {
    mix.browserSync({
        proxy: 'project.dev'
    });
});