Laravel 8.x アセットのコンパイル（Mix）

イントロダクションIntroduction

Laravel Mixは、Laracastsを作ったJeffrey Wayが開発したパッケージで、webpackを定義するためスラスラと書けるAPIを提供しています。多くの一般的なCSSおよびJavaScriptプリプロセッサを使用してLaravelアプリケーションのビルドステップを定義します。Laravel Mix[https://github.com/JeffreyWay/laravel-mix], a package developed by Laracasts[https://laracasts.com] creator Jeffrey Way, provides a fluent API for defining webpack[https://webpack.js.org] build steps for your Laravel application using several common CSS and JavaScript pre-processors.

言い換えると、Mixを使用すると、アプリケーションのCSSファイルとJavaScriptファイルを簡単にコンパイルして圧縮できます。シンプルなメソッドチェーンにより、アセットパイプラインを流暢に定義できます。例をご覧ください。In other words, Mix makes it a cinch to compile and minify your application's CSS and JavaScript files. Through simple method chaining, you can fluently define your asset pipeline. For example:

mix.js('resources/js/app.js', 'public/js')
    .postCss('resources/css/app.css', 'public/css');

Webpackとアセットのコンパイルを使い始めようとして混乱し圧倒されたことがある方は、Laravel Mixを気に入ってくれるでしょう。ただし、アプリケーションの開発に必ず使用する必要はありません。お好きなアセットパイプラインツールを使用するも、まったく使用しないのも自由です。If you've ever been confused and overwhelmed about getting started with webpack and asset compilation, you will love Laravel Mix. 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.

lightbulb">Tip!! LaravelとTailwind CSSを使用してアプリケーションの構築を早急に開始する必要がある場合は、アプリケーションスターターキットのいずれかをチェックしてください。{tip} If you need a head start building your application with Laravel and Tailwind CSS[https://tailwindcss.com], check out one of our application starter kits[/docs/{{version}}/starter-kits].

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

NodeのインストールInstalling Node

Mixを実行する前に、まずNode.jsとNPMをマシンへ確実にインストールする必要があります。Before running Mix, you must first ensure that Node.js and NPM are installed on your machine:

node -v
npm -v

Nodeの公式ウェブサイトから簡単なグラフィカルインストーラを使用して、最新バージョンのNodeとNPMを簡単にインストールできます。または、Laravel Sailを使用している場合は、Sailを介してNodeとNPMを呼び出すことができます。You can easily install the latest version of Node and NPM using simple graphical installers from the official Node website[https://nodejs.org/en/download/]. Or, if you are using Laravel Sail[/docs/{{version}}/sail], you may invoke Node and NPM through Sail:

./sail node -v
./sail npm -v

Laravel MixのインストールInstalling Laravel Mix

残りの唯一のステップは、Laravel Mixをインストールすることです。Laravelの新規インストールでは、ディレクトリ構造のルートにpackage.jsonファイルがあります。デフォルトのpackage.jsonファイルには、Laravel Mixの使用を開始するために必要なすべてのものがすでに含まれています。このファイルは、PHPの依存関係ではなくNodeの依存関係を定義することを除けば、composer.jsonファイルと同じように考えてください。以下を実行して、参照する依存関係をインストールします。The only remaining step is to install Laravel Mix. 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 already includes everything you need to get started using Laravel Mix. Think of this file like your composer.json file, except it defines Node dependencies instead of PHP dependencies. You may install the dependencies it references by running:

npm install

Mixの実行Running Mix

Mixはwebpackの上の設定レイヤーであるため、Mixタスクを実行するには、デフォルトのLaravel package.jsonファイルに含まれているNPMスクリプトの１つを実行するだけです。devまたはproductionスクリプトを実行すると、アプリケーションのすべてのCSSおよびJavaScriptアセットがコンパイルされ、アプリケーションのpublicディレクトリへ配置されます。Mix is a configuration layer on top of webpack[https://webpack.js.org], so to run your Mix tasks you only need to execute one of the NPM scripts that are included in the default Laravel package.json file. When you run the dev or production scripts, all of your application's CSS and JavaScript assets will be compiled and placed in your application's public directory:

// すべてのMixタスクを実行...
npm run dev

// すべてのMixタスクを実行し、出力を圧縮。
npm run prod

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

npm run watchコマンドはターミナルで実行され続け、関連するすべてのCSSファイルとJavaScriptファイルの変更を監視します。Webpackは、こうしたファイルのいずれか一つの変更を検出すると、アセットを自動的に再コンパイルします。The npm run watch command will continue running in your terminal and watch all relevant CSS and JavaScript files for changes. Webpack will automatically recompile your assets when it detects a change to one of these files:

npm run watch

Webpackは、特定のローカル開発環境でファイルの変更を検出できない場合があります。これがシステムに当てはまる場合は、watch-pollコマンドの使用を検討してください。Webpack may not be able to detect your file changes in certain local development environments. If this is the case on your system, consider using the watch-poll command:

npm run watch-poll

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

アプリケーションのwebpack.mix.jsファイルは、すべてのアセットをコンパイルするためのエントリポイントです。webpackの軽い設定ラッパーと考えてください。ミックスタスクをチェーン化して、アセットのコンパイル方法を正確に定義できます。Your application's webpack.mix.js file is your entry point for all asset compilation. Think of it as a light configuration wrapper around webpack[https://webpack.js.org]. Mix tasks can be chained together to define exactly how your assets should be compiled.

Tailwind CSSTailwind CSS

Tailwind CSSは、HTMLを離れることなく、すばらしいサイトを構築するための最新のユーティリティファーストフレームワークです。Laravel Mixを使用したLaravelプロジェクトでこれを使い始める方法を掘り下げてみましょう。まず、NPMを使用してTailwindをインストールし、Tailwind設定ファイルを生成する必要があります。Tailwind CSS[https://tailwindcss.com] is a modern, utility-first framework for building amazing sites without ever leaving your HTML. Let's dig into how to start using it in a Laravel project with Laravel Mix. First, we should install Tailwind using NPM and generate our Tailwind configuration file:

npm install

npm install -D tailwindcss

npx tailwindcss init

initコマンドはtailwind.config.jsファイルを生成します。このファイルのcontentセクションでは、HTML テンプレート、JavaScript コンポーネント、その他 Tailwind のクラス名を含むソースファイルへのパスを設定することができ、これらのファイル内で使用されていないCSSクラスを本番環境のCSSビルドからパージします。The init command will generate a tailwind.config.js file. The content section of this file allows you to configure the paths to all of your HTML templates, JavaScript components, and any other source files that contain Tailwind class names so that any CSS classes that are not used within these files will be purged from your production CSS build:

content: [
    './storage/framework/views/*.php',
    './resources/**/*.blade.php',
    './resources/**/*.js',
    './resources/**/*.vue',
],

次に、Tailwindの各「レイヤー」をアプリケーションのresources/css/app.cssファイルに追加する必要があります。Next, you should add each of Tailwind's "layers" to your application's resources/css/app.css file:

@tailwind base;
@tailwind components;
@tailwind utilities;

Tailwindのレイヤーを設定したら、アプリケーションのwebpack.mix.jsファイルを更新して、Tailwindを利用したCSSをコンパイルする準備が整います。Once you have configured Tailwind's layers, you are ready to update your application's webpack.mix.js file to compile your Tailwind powered CSS:

mix.js('resources/js/app.js', 'public/js')
    .postCss('resources/css/app.css', 'public/css', [
        require('tailwindcss'),
    ]);

最後に、アプリケーションのプライマリレイアウトテンプレートでスタイルシートを参照する必要があります。多くのアプリケーションは、このテンプレートをresources/views/layouts/app.blade.phpに保存することを選択します。さらに、レスポンシブビューポートのmetaタグがまだ存在しない場合は、必ず追加してください。Finally, you should reference your stylesheet in your application's primary layout template. Many applications choose to store this template at resources/views/layouts/app.blade.php. In addition, ensure you add the responsive viewport meta tag if it's not already present:

<head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <link href="/css/app.css" rel="stylesheet">
</head>

PostCSSPostCSS

PostCSSは、CSSを変換するための強力なツールであり、Laravel Mixにはじめから含まれています。デフォルトで、Mixは人気のあるAutoprefixerプラグインを利用して、必要なすべてのCSS3ベンダープレフィックスを自動的に適用します。ただし、アプリケーションに適したプラグインを自由に追加できます。PostCSS[https://postcss.org/], a powerful tool for transforming your CSS, is included with Laravel Mix out of the box. By default, Mix leverages the popular Autoprefixer[https://github.com/postcss/autoprefixer] plugin to automatically apply all necessary CSS3 vendor prefixes. However, you're free to add any additional plugins that are appropriate for your application.

まず、NPMを介して希望するプラグインをインストールし、MixのpostCssメソッドを呼び出すときにプラグインの配列に含めます。postCssメソッドは、CSSファイルへのパスを最初の引数に取り、コンパイルしたファイルを配置するディレクトリを２番目の引数に取ります。First, install the desired plugin through NPM and include it in your array of plugins when calling Mix's postCss method. The postCss method accepts the path to your CSS file as its first argument and the directory where the compiled file should be placed as its second argument:

mix.postCss('resources/css/app.css', 'public/css', [
    require('postcss-custom-properties')
]);

または、単純なCSSのコンパイルと圧縮を実現するために、追加のプラグインなしでpostCssを実行することもできます。Or, you may execute postCss with no additional plugins in order to achieve simple CSS compilation and minification:

mix.postCss('resources/css/app.css', 'public/css');

SassSass

sassメソッドを使用すると、SassをWebブラウザで理解できるCSSにコンパイルできます。sassメソッドは、Sassファイルへのパスを最初の引数に取り、コンパイルしたファイルを配置するディレクトリを２番目の引数に取ります。The sass method allows you to compile Sass[https://sass-lang.com/] into CSS that can be understood by web browsers. The sass method accepts the path to your Sass file as its first argument and the directory where the compiled file should be placed as its second argument:

mix.sass('resources/sass/app.scss', 'public/css');

複数のSassファイルをそれぞれのCSSファイルにコンパイルし、sassメソッドを複数回呼び出すことで、結果のCSSの出力ディレクトリをカスタマイズすることもできます。You may compile multiple Sass files into their own respective CSS files and even customize the output directory of the resulting CSS by calling the sass method multiple times:

mix.sass('resources/sass/app.sass', 'public/css')
    .sass('resources/sass/admin.sass', 'public/css/admin');

URL処理URL Processing

LaravelMixはwebpackの上に構築されているため、いくつかのwebpackの概念を理解することが重要です。CSSコンパイルの場合、webpackはスタイルシート内のurl()呼び出しを書き直して最適化します。これは最初は奇妙に聞こえるかもしれませんが、信じられないほど強力な機能です。画像への相対URLを含むSassをコンパイルしたいとします。Because Laravel Mix is built on top of webpack, it's important to understand a few webpack concepts. For CSS compilation, webpack will rewrite and optimize any url() calls within your stylesheets. While this might initially sound strange, it's an incredibly powerful piece of functionality. Imagine that we want to compile Sass that includes a relative URL to an image:

.example {
    background: url('../images/example.png');
}

Note: note url()へ指定された絶対パスはURLの書き換えから除外されます。たとえば、url('/images/thing.png')またはurl('http://example.com/images/thing.png')は変更されません。{note} Absolute paths for any given url() will be excluded from URL-rewriting. For example, url('/images/thing.png') or url('http://example.com/images/thing.png') won't be modified.

デフォルトでは、Laravel Mixとwebpackはexample.pngを見つけ、それをpublic/imagesフォルダにコピーしてから、生成されたスタイルシート内のurl()を書き換えます。そのため、コンパイルされたCSSは次のようになります。By default, Laravel Mix and webpack will find example.png, copy it to your public/images folder, and then rewrite the url() within your generated stylesheet. As such, your compiled CSS will be:

.example {
    background: url(/images/example.png?d41d8cd98f00b204e9800998ecf8427e);
}

この機能は便利かもしれませんが、皆さん既にお好みの方法でフォルダ構造を構成しているでしょう。この場合、次のようにurl()の書き換えを無効にすることができます。As useful as this feature may be, your existing folder structure may already be configured in a way you like. If this is the case, you may disable url() rewriting like so:

mix.sass('resources/sass/app.scss', 'public/css').options({
    processCssUrls: false
});

このwebpack.mix.jsファイルの変更により、Mixはurl()と一致しなくなり、アセットをパブリックディレクトリにコピーしなくなります。つまり、コンパイルされたCSSは、最初に入力した方法と同じようになります。With this addition to your webpack.mix.js file, Mix will no longer match any url() or copy assets to your public directory. In other words, the compiled CSS will look just like how you originally typed it:

.example {
    background: url("../images/thing.png");
}

ソースマップSource Maps

デフォルトでは無効になっていますが、ソースマップはwebpack.mix.jsファイルのmix.sourceMaps()メソッドを呼び出すことでアクティブにできます。コンパイル／パフォーマンスのコストが伴いますが、これにより、コンパイルされたアセットを使用するときに、ブラウザの開発者ツールに追加のデバッグ情報が提供されます。Though disabled by default, source maps may be activated by calling the mix.sourceMaps() method in your webpack.mix.js file. Though it comes with a compile/performance cost, this will provide extra debugging information to your browser's developer tools when using compiled assets:

mix.js('resources/js/app.js', 'public/js')
    .sourceMaps();

ソースマッピングのスタイルStyle Of Source Mapping

Webpackは、さまざまなソースマッピングスタイルを提供しています。デフォルトでは、Mixのソースマッピングスタイルはeval-source-mapに設定されており、これにより再構築時間が短縮されます。マッピングスタイルを変更したい場合は、sourceMapsメソッドを使用して変更できます。Webpack offers a variety of source mapping styles[https://webpack.js.org/configuration/devtool/#devtool]. By default, Mix's source mapping style is set to eval-source-map, which provides a fast rebuild time. If you want to change the mapping style, you may do so using the sourceMaps method:

let productionSourceMaps = false;

mix.js('resources/js/app.js', 'public/js')
    .sourceMaps(productionSourceMaps, 'source-map');

JavaScriptの操作Working With JavaScript

Mixは、現代的なECMAScriptのコンパイル、モジュールのバンドル、圧縮、プレーンなJavaScriptファイルの連結など、JavaScriptファイルの操作に役立つの機能をいくつか提供します。さらに良いことに、これはすべてシームレスに機能し、大量のカスタム設定を必要としません。Mix provides several features to help you work with your JavaScript files, such as compiling modern ECMAScript, module bundling, minification, and concatenating plain JavaScript files. Even better, this all works seamlessly, without requiring an ounce of custom configuration:

mix.js('resources/js/app.js', 'public/js');

この１行のコードで、次の利点を活用できます。With this single line of code, you may now take advantage of:

VueVue

Mixは、vueメソッドを使用するときに、Vue単一ファイルコンポーネントのコンパイルサポートに必要なBabelプラグインを自動的にインストールします。これ以上の設定は必要ありません。Mix will automatically install the Babel plugins necessary for Vue single-file component compilation support when using the vue method. No further configuration is required:

mix.js('resources/js/app.js', 'public/js')
   .vue();

JavaScriptがコンパイルされたら、アプリケーションから参照できます。Once your JavaScript has been compiled, you can reference it in your application:

<head>
    <!-- ... -->

    <script src="/js/app.js"></script>
</head>

ReactReact

MixはReactサポートに必要なBabelプラグインを自動的にインストールします。利用開始するには、reactメソッドの呼び出しを追加してください。Mix can automatically install the Babel plugins necessary for React support. To get started, add a call to the react method:

mix.js('resources/js/app.jsx', 'public/js')
   .react();

裏でMixは適切なbabel-preset-react Babelプラグインをダウンロードして取り込みます。JavaScriptをコンパイルしたら、アプリケーションから参照できます。Behind the scenes, Mix will download and include the appropriate babel-preset-react Babel plugin. Once your JavaScript has been compiled, you can reference it in your application:

<head>
    <!-- ... -->

    <script src="/js/app.js"></script>
</head>

ベンダーの抽出Vendor Extraction

アプリケーション固有のJavaScriptをすべてReactやVueなどのベンダーライブラリへバンドルすることの潜在的な欠点のひとつは、長期的なキャッシュが困難になることです。たとえば、アプリケーションコードを１回更新すると、変更されていない場合でも、ブラウザはすべてのベンダーライブラリを再ダウンロードする必要があります。One potential downside to bundling all of your application-specific JavaScript with your vendor libraries such as React and Vue is that it makes long-term caching more difficult. For example, a single update to your application code will force the browser to re-download all of your vendor libraries even if they haven't changed.

アプリケーションのJavaScriptを頻繁に更新する場合は、すべてのベンダーライブラリを独自のファイルに抽出することを検討する必要があります。この方法により、アプリケーションコードを変更しても、大きなvendor.jsファイルのキャッシュには影響しません。Mixのextractメソッドはこれを簡単にします:If you intend to make frequent updates to your application's JavaScript, you should consider extracting all of your vendor libraries into their own file. This way, a change to your application code will not affect the caching of your large vendor.js file. Mix's extract method makes this a breeze:

mix.js('resources/js/app.js', 'public/js')
    .extract(['vue'])

extractメソッドは、vendor.jsファイルに抽出したいすべてのライブラリまたはモジュールの配列を受け入れます。上記のスニペットを例として使用すると、Mixは次のファイルを生成します。The extract method accepts an array of all libraries or modules that you wish to extract into a vendor.js file. Using the snippet above as an example, Mix will generate the following files:

JavaScriptエラーを回避するため、以下のファイルを正しい順序でロードしてください。To avoid JavaScript errors, be sure to load these files in the proper order:

<script src="/js/manifest.js"></script>
<script src="/js/vendor.js"></script>
<script src="/js/app.js"></script>

Webpackカスタム設定Custom Webpack Configuration

時折、ベースとなるWebpack設定を手動で変更する必要が起きるでしょう。たとえば、参照する必要がある特別なローダーまたはプラグインがある可能性があります。Occasionally, you may need to manually modify the underlying Webpack configuration. For example, you might have a special loader or plugin that needs to be referenced.

Mixは、短いWebpack設定オーバーライドをマージできる便利なwebpackConfigメソッドを提供します。これは、webpack.config.jsファイルの独自のコピーをコピーして維持する必要がないため、特に魅力的です。webpackConfigメソッドはオブジェクトを受け入れます。オブジェクトには、適用するWebpack固有の設定が含まれている必要があります。Mix provides a useful webpackConfig method that allows you to merge any short Webpack configuration overrides. This is particularly appealing, as it doesn't require you to copy and maintain your own copy of the webpack.config.js file. The webpackConfig method accepts an object, which should contain any Webpack-specific configuration[https://webpack.js.org/configuration/] that you wish to apply.

mix.webpackConfig({
    resolve: {
        modules: [
            path.resolve(__dirname, 'vendor/laravel/spark/resources/assets/js')
        ]
    }
});

バージョニング／キャッシュの破棄Versioning / Cache Busting

多くの開発者は、コンパイルしたアセットにタイムスタンプまたは一意のトークンの接尾辞を付けて、提供してきたコードの古くなったコピーの代わりに、ブラウザに新しいアセットをロードするように強制します。Mixは、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. Mix can automatically handle this for you using the version method.

versionメソッドは、コンパイルしたすべてのファイルのファイル名に一意のハッシュを追加し、より便利なブラウザキャッシュ破棄を可能にしています。The version method will append a unique hash to the filenames of all compiled files, allowing for more convenient cache busting:

mix.js('resources/js/app.js', 'public/js')
    .version();

バージョン付きファイルを生成すると、正確なファイル名がわからなくなります。したがって、views内でLaravelのグローバルなmix関数を使用して、適切にハッシュされたアセットをロードする必要があります。mix関数は、ハッシュされたファイルの現在の名前を自動的に判別します。After generating the versioned file, you won't know the exact filename. So, you should use Laravel's global mix function within your views[/docs/{{version}}/views] to load the appropriately hashed asset. The mix function will automatically determine the current name of the hashed file:

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

通常、バージョン付きファイルは開発では不要であるため、npm run prodの実行中にのみ実行するよう、バージョン付け処理に指示できます。Because versioned files are usually unnecessary in development, you may instruct the versioning process to only run during npm run prod:

mix.js('resources/js/app.js', 'public/js');

if (mix.inProduction()) {
    mix.version();
}

カスタムMixベースURLCustom Mix Base URLs

Mixでコンパイルされたアセットをアプリケーションとは別のCDNにデプロイする場合は、mix関数にが生成するベースURLを変更する必要があります。これには、アプリケーションのconfig/app.php設定ファイルにmix_url設定オプションを追加します。If your Mix compiled assets are deployed to a CDN separate from your application, you will need to change the base URL generated by the mix function. You may do so by adding a mix_url configuration option to your application's config/app.php configuration file:

'mix_url' => env('MIX_ASSET_URL', null)

Mix URLを設定すると、以降はアセットへのURLを生成するときに、mix関数は設定したURLのプレフィックスを付けます。After configuring the Mix URL, The mix function will prefix the configured URL when generating URLs to assets:

https://cdn.example.com/js/app.js?id=1964becbdd96414518cd

BrowsersyncによるリロードBrowsersync Reloading

BrowserSyncは、ファイルの変更を自動的に監視し、手動で更新しなくても変更をブラウザに反映できます。mix.browserSync()メソッドを呼び出すことにより、これのサポートを有効にすることができます。BrowserSync[https://browsersync.io/] can automatically monitor your files for changes, and inject your changes into the browser without requiring a manual refresh. You may enable support for this by calling the mix.browserSync() method:

mix.browserSync('laravel.test');

BrowserSyncオプションは、JavaScriptオブジェクトをbrowserSyncメソッドに渡すことで指定できます。BrowserSync options[https://browsersync.io/docs/options] may be specified by passing a JavaScript object to the browserSync method:

mix.browserSync({
    proxy: 'laravel.test'
});

次に、npm run watchコマンドを使用してwebpackの開発サーバを起動します。これで、スクリプトまたはPHPファイルを変更すると、ブラウザがページを即座に更新して、変更を反映するのを目にできるでしょう。Next, start webpack's development server using the npm run watch command. Now, when you modify a script or PHP file you can watch as the browser instantly refreshes the page to reflect your changes.

環境変数Environment Variables

.envファイルの環境変数の1つにMIX_のプレフィックスを付けることで、環境変数をwebpack.mix.jsスクリプトに挿入できます。You may inject environment variables into your webpack.mix.js script by prefixing one of the environment variables in your .env file with MIX_:

MIX_SENTRY_DSN_PUBLIC=http://example.com

変数を.envファイルで定義したら、以降はprocess.envオブジェクトを介して変数へアクセスできます。ただし、タスクの実行中に環境変数の値が変更された場合は、タスクを再起動する必要があります。After the variable has been defined in your .env file, you may access it via the process.env object. However, you will need to restart the task if the environment variable's value changes while the task is running:

process.env.MIX_SENTRY_DSN_PUBLIC

通知Notifications

利用可能な場合、Mixはコンパイル時にＯＳ通知を自動的に表示し、コンパイルが成功したかを即座にフィードバックします。しかし、これらの通知を無効にしたい状況もあるでしょう。そのような例の１つは、本番サーバでMixをトリガーするときです。通知は、disableNotificationsメソッドを使用して非アクティブ化できます。When available, Mix will automatically display OS notifications when compiling, giving you instant feedback as to whether the compilation was successful or not. However, there may be instances when you would prefer to disable these notifications. One such example might be triggering Mix on your production server. Notifications may be deactivated using the disableNotifications method:

mix.disableNotifications();