Laravel 7.x アセットのコンパイル(Mix)

イントロダクション

Laravel Mixは多くの一般的なCSSとJavaScriptのプリプロセッサを使用し、Laravelアプリケーションために、構築過程をwebpackでスラスラと定義できるAPIを提供しています。シンプルなメソッドチェーンを使用しているため、アセットパイプラインを流暢に定義できます。例を見てください。

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

webpackやアセットのコンパイルを始めようとして、混乱と圧倒を感じているならLaravel Mixを気に入ってもらえるでしょう。しかし、アプリケーションの開発時に必要だというわけではありません。どんなアセットパイプラインツールを使用してもかまいませんし、使わなくても良いのです。

インストールと準備

Nodeのインストール

Mixを始める前、最初にNode.jsとNPMを開発機へ確実にインストールしてください。

node -v
npm -v

Laravel Homesteadならデフォルトのままでも必要なものが全部そろっています。しかし、Vagrantを使っていなくても、ダウンロードページを読めば、NodeとNPMは簡単にインストールできます。

Laravel Mix

残っているステップはLaravel Mixのインストールだけです。新しくLaravelをインストールすると、ルートディレクトリにpackage.jsonがあることに気づくでしょう。PHPの代わりにNodeの依存パッケージが定義されている所が異なりますが、composer.jsonファイルに似た構成ファイルだと考えてください。以下のコマンドで、依存パッケージをインストールしてください。

npm install

Mixの実行

Mixはwebpack上の設定レイヤーですから、Laravelに含まれるpackage.jsonファイル上のNPMスクリプトの一つをMixの実行で起動してください。

// 全タスク実行
npm run dev

// 全タスク実行を実行し、出力を圧縮
npm run production

アセット変更の監視

npm run watchコマンドはターミナルで実行し続け、関連ファイル全部の変更を監視します。webpackは変更を感知すると、アセットを自動的に再コンパイルします。

npm run watch

特定の環境のwebpackでは、ファイル変更時に更新されないことがあります。自分のシステムでこれが起きた場合は、watch-pollコマンドを使用してください。

npm run watch-poll

スタイルシートの操作

webpack.mix.jsファイルは全アセットコンパイルのエントリポイントです。webpackの軽い設定ラッパーだと考えてください。Mixタスクはアセットをどのようにコンパイルすべきかを正確に定義するため、チェーンでつなげます。

Less

LessをCSSへコンパイルするにはlessメソッドを使用します。一番主要なapp.lessファイルをpublic/css/app.cssとしてコンパイルしてみましょう。

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

複数のファイルをコンパイルするには、lessメソッドを複数回呼び出します。

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

コンパイル済みのCSSのファイル名をカスタマイズしたい場合は、lessの第２引数にファイルのフルパスを指定してください。

mix.less('resources/less/app.less', 'public/stylesheets/styles.css');

裏で動作しているLessプラグインのオプションをオーバーライドする必要が起きたら、mix.less()の第３引数にオブジェクトを渡してください。

mix.less('resources/less/app.less', 'public/css', {
    strictMath: true
});

Sass

sassメソッドは、SassをCSSへコンパイルします。次のように使用します。

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

lessメソッドと同様に、複数のSassファイルを別々のCSSファイルへコンパイルできますし、結果のCSSの出力ディレクトリをカスタマイズ可能です。

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

さらに、Node-Sassプラグインオプションを第３引数に指定できます。

mix.sass('resources/sass/app.sass', 'public/css', {
    precision: 5
});

Stylus

LessやSassと同様に、stylusメソッドにより、StylusをCSSへコンパイルできます。

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

さらに、Ruptureのような、追加のStylusプラグインをインストールすることもできます。最初に、NPM（npm install rupture）による質問でプラグインをインストールし、それからmix.stylus()の中で呼び出してください。

mix.stylus('resources/stylus/app.styl', 'public/css', {
    use: [
        require('rupture')()
    ]
});

PostCSS

強力なCSS加工ツールであるPostCSSも、Laravel Mixには最初から含まれています。デフォルトでは、自動的に必要なCSS3ベンダープレフィックスを適用する、人気のAutoprefixerプラグインを利用します。しかし、アプリケーションに適したプラグインを自由に追加できます。最初に、NPMにより希望のプラグインをインストールし、それからwebpack.mix.jsの中から参照してください。

mix.sass('resources/sass/app.scss', 'public/css')
    .options({
        postCss: [
            require('postcss-css-variables')()
        ]
    });

平文CSS

平文のCSSスタイルシートを一つのファイルへ結合したい場合は、stylesメソッドを使ってください。

mix.styles([
    'public/css/vendor/normalize.css',
    'public/css/vendor/videojs.css'
], 'public/css/all.css');

URL処理

Laravel Mixはwebpack上に構築されているため、webpackのコンセプトを理解することが重要です。CSSコンパイルのため、webpackはスタイルシート中のurl()呼び出しをリライトし、最適化します。最初は奇妙に聴こえるかもしれませんが、これは非常に強力な機能の一部です。画像への相対URLを含んだSassをコンパイルするのを想像してください。

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

Note: 絶対パスをurl()へ指定しても、URL書き換えの対象外になります。たとえば、url('/images/thing.png')や、url('http://example.com/images/thing.png')は変更されません。

デフォルト動作として、Laravel Mixとwebpackがexample.pngを見つけると、それをpublic/imagesフォルダへコピーします。それから、生成したスタイルシート中のurl()を書き換えます。

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

この機能は便利ですが、好きなようにフォルダ構造を設定することもできます。その場合、以下のようにurl()リライトを停止してください。

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

これをwebpack.mix.jsファイルへ追加することで、Mixはどんなurl()に一致することも、publicディレクトリへアセットをコピーすることもしなくなります。言い換えれば、コンパイル済みのCSSは、みなさんがタイプした内容そのままに見えるでしょう。

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

ソースマップ

デフォルトでは無効になっているため、webpack.mix.jsファイルでmix.sourceMaps()を呼び出すことで、ソースマップは有効になります。コンパイルコストと実行パフォーマンスコストはかかりますが、これによりコンパイル済みアセットを使用する時に、ブラウザの開発ツール向けの追加デバッグ情報が提供されます。

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

ソースマップのスタイル

webpackはさまざまなソースマップスタイルを提供しています。Mixはソースマッピングスタイルのデフォルトとして、ブルド時間の早い eval-source-mapをセットしています。マッピングスタイルを変更したい場合は、 sourceMapsメソッドを使用してください。

let productionSourceMaps = false;

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

JavaScriptの操作

MixはECMAScript 2015のコンパイル、モジュール結合、圧縮やJavaScriptファイルの結合などの操作を手助けする、多くの機能を提供しています。それだけでなく、設定をカスタマイズする必要はまったく無く、すべてがシームレスに動作します。

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

このコード一行で、以下の利点を享受できます。

  • ES2015記法
  • モジュール
  • .vueファイルのコンパイル
  • 開発環境向けに圧縮

ベンダの抽出

すべてのアプリケーション固有のJavaScriptとベンダーライブラリを結合することにより、発生する可能性がある欠点は、長期間のキャッシュが効きづらくなることです。たとえば、アプリケーションコードの一箇所を更新すれば、変更のないベンダーライブラリーのすべてを再度ダウンロードするように、ブラウザに強要します。

アプリケーションのJavaScriptを頻繁に更新したい場合は、全ベンダーライブラリを専用のファイルへ分ける方法を考慮する必要があります。これにより、アプリケーションコードの変更は、大きなvendor.jsファイルのキャッシュへ影響しなくなります。Mixのextractメソッドで簡単に実現できます。

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

extractメソッドは全ライブラリとモジュールの配列を受け取り、vendor.jsへ別にまとめます。上記のコードを例にすると、Mix配下のファイルを生成します。

  • public/js/manifest.js: webpackマニフェストランタイム
  • public/js/vendor.js: ベンダーライブラリ
  • public/js/app.js: アプリケーションコード

JavaScriptエラーを起こさないために、以下のファイルは順番通りにロードしてください。

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

React

MixはReactをサポートするために、Babelプラグインを自動的にインストールします。使用開始するためには、mix.js()の呼び出しをmix.react()に置換してください。

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

実際には、Mixは最適なBabelプラグインとしてbabel-preset-reactをダウンロードし、取り込んでいます。

バニラJS

スタイルシートをmix.styles()により結合するのと同様に、多くのJavaScriptファイルをscripts()メソッドで結合し、圧縮できます。

mix.scripts([
    'public/js/admin.js',
    'public/js/dashboard.js'
], 'public/js/all.js');

この選択肢はとくにwebpackによる操作を必要としないレガシープロジェクトに便利です。

Tip!! mix.scripts()のちょっとしたバリエーションとしてmix.babel()があります。このメソッドはscriptsと同じ使い方です。しかし、結合したファイルはBabelにより編集され、ES2015コードをすべてのブラウザーが理解できるバニラJavaScriptへ変換します。

webpackカスタム設定

Laravel Mixはできるだけ素早く実行できるように、裏で事前に設定済みのwebpack.config.jsファイルを参照しています。ときどき、このファイルを変更する必要が起きるでしょう。参照する必要がある特別なローダやプラグインがあったり、Sassの代わりにStylusを使うのが好みであるかもしれません。そうした場合、２つの選択肢があります。

カスタム設定のマージ

Mixはオーバーライドする短いwebpack設定をマージできるように、便利なwebpackConfigメソッドを提供しています。これは、webpack.config.jsファイルをコピーし、独自バージョンをメンテナンスする必要がないため、やや魅力的な選択しです。webpackConfigメソッドは、適用したいwebpack限定設定を含むオブジェクトを引数に取ります。

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

カスタム設定ファイル

webpack設定をすべてカスタマイズしたい場合は、node_modules/laravel-mix/setup/webpack.config.jsをプロジェクトのルートディレクトリへコピーしてください。次に、package.jsonファイル中の--config参照をすべて新しくコピーした設定ファイルに変更します。カスタマイズにこのアプローチを取る場合は、Mixのwebpack.config.jsに対するアップストリームの機能変更を自分でカスタマイズするファイルへマージする必要があります。

ファイル／ディレクトリコピー

copyメソッドは、ファイルやディレクトリを新しい場所へコピーします。これはnode_modulesディレクトリ中の特定のアセットをpublicフォルダへ再配置する必要がある場合に便利です。

mix.copy('node_modules/foo/bar.css', 'public/css/bar.css');

ディレクトリのコピー時は、copyメソッドはディレクトリ構造をフラットにします。元の構造を保持したい場合は、copyDirectoryメソッドを代わりに使用してください。

mix.copyDirectory('resources/img', 'public/img');

バージョン付け／キャッシュ対策

多くの開発者は古いコードが提供され続けないように、新しいアセットがブラウザにロードされるよう、タイムスタンプやユニークなトークンをコンパイル済みのアセットへサフィックスとして付加しています。Mixでは、versionメソッドを使用し、これを処理できます。

versionメソッドは、キャッシュを簡単に破壊できるようにするため、コンパイル済みファイルのファイル名に一意のハッシュを自動的に付け加えます。

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

バージョン付されたファイルを生成した後は、適切にバージョン付けされたアセットのURLを生成するため、Laravelのグローバルmix関数をビューの中で使用してください。

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

バージョン付けしたファイルは、通常開発に必要ないため、npm run productionを実行するときのみ、バージョン付けするように指示したいと思うでしょう。

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

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

MixのベースURLのカスタマイズ

アプリケーションから独立して、MixがコンパイルしたアセットをCDNへデプロイしている場合は、mix関数が生成するベースURLを変更する必要があります。そのためには、config/app.php設定ファイルへmix_url設定オプションを追加してください。

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

MixのURLを設定後、mix関数はアセットへのURLを生成する場合に、設定したURLを使用します。

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

Browsersyncリロード

BrowserSyncは自動的にファイルの変更を監視し、手動で再読込しなくても変更をブラウザに反映してくれます。mix.browserSync()メソッドを呼び出し、有効にします。

mix.browserSync('my-domain.test');

// もしくは

// https://browsersync.io/docs/options
mix.browserSync({
    proxy: 'my-domain.test'
});

このメソッドには文字列（プロキシ）かオブジェクト（BrowserSync設定）のどちらかを渡します。次に、npm run watchコマンドにより、webpackの開発サーバを起動します。これでスクリプトかPHPファイルを変更すると、すぐにページが再読込され、変更が反映されるのを目にするでしょう。

環境変数

.envファイルの中でキーにMIX_をプリフィックスとしてつけることで、環境変数をMixへ注入できます。

MIX_SENTRY_DSN_PUBLIC=http://example.com

.envファイルで定義すると、process.envオブジェクトを通じてアクセスできるようになります。watchタスク実行中に、その値が変化した場合は、タスクを再起動する必要があります。

process.env.MIX_SENTRY_DSN_PUBLIC

通知

可能な場合、Mixは自動的に各バンドルをＯＳ通知で表示します。これにより、コンパイルが成功したのか、失敗したのか、即座にフィードバックが得られます。しかし、こうした通知を無効にしたい場合もあるでしょう。一例は、実働サーバでMixを起動する場合です。disableNotificationsメソッドにより、通知を無効にできます。

mix.disableNotifications();

ドキュメント章別ページ

前章
リリースノート アップグレードガイド 貢献ガイド
API
APIドキュメント
準備
インストール 設定 ディレクトリ構造 Homestead Valet デプロイ
構成の概念
ライフサイクル サービスコンテナ サービスプロバイダ ファサード 契約
基礎
ルーティング ミドルウェア CSRF保護 コントローラ リクエスト レスポンス ビュー URL生成 セッション バリデーション エラー処理 ログ
フロントエンド
Bladeテンプレート 多言語化 スカフォールド アセットコンパイル
セキュリティ
認証 認可 メール確認 暗号化 ハッシュ パスワードリセット
より深く知る
Artisanコンソール ブロードキャスト キャッシュ コレクション イベント ファイルストレージ ヘルパ HTTPクライアント メール 通知 パッケージ開発 キュー タスクスケジュール
データベース
データベースの準備 クエリビルダ ペジネーション マイグレーション シーディング Redis
Eloquent ORM
Eloquentの準備 リレーション コレクション ミューテタ APIリソース シリアライズ
テスト
テストの準備 HTTPテスト コンソールテスト ブラウザテスト データベース モック
公式パッケージ
Cashier (Stripe) Cashier (Paddle) Cashier (Mollie) Dusk Envoy Horizon Passport Sanctum Scout Socialite Telescope
言語 ファイル
auth.php pagination.php passwords.php validation.php

ヘッダー項目移動

注目：アイコン：ページ内リンク設置（リンクがないヘッダーへの移動では、リンクがある以前のヘッダーのハッシュをURLへ付加します。

移動

クリックで即時移動します。

リンク
サイトホーム ページ上部へ
言語
バージョン
10.x 9.x 8.x 7.x 6.x LTS 5.8 5.7 5.6 5.5 LTS 5.4 5.3 5.2 5.1 LTS 5.0 5.dev 4.2

設定

適用ボタンクリック後に、全項目まとめて適用されます。

カラーテーマ
和文指定 Pagination
和文指定 Scaffold
Largeスクリーン表示幅
インデント
本文フォント
コードフォント
フォント適用確認

フォントの指定フィールドから、フォーカスが外れると、当ブロックの内容に反映されます。EnglishのDisplayもPreviewしてください。

フォント設定時、表示に不具合が出た場合、当サイトのクッキーを削除してください。

バックスラッシュを含むインライン\Code\Blockの例です。

以下はコードブロックの例です。

<?php

namespace App;

use Illuminate\Database\Eloquent\Model;

class User extends Model
{
    /**
     * ユーザに関連する電話レコードを取得
     */
    public function phone()
    {
        return $this->hasOne('App\Phone');
    }
}

設定を保存する前に、表示が乱れないか必ず確認してください。CSSによるフォントファミリー指定の知識がない場合は、フォントを変更しないほうが良いでしょう。

キーボード・ショートカット

オープン操作

P／D／C

ページ（章）移動の左オフキャンバスオープン

H／A

ヘッダー移動モーダルオープン

M／S

移動／設定の右オフキャンバスオープン

ヘッダー移動

T

最初のヘッダーへ移動

E

最後のヘッダーへ移動

N／J

次ヘッダー(H2〜H4)へ移動

B／K

前ヘッダー(H2〜H4)へ移動

その他

?

このヘルプページ表示
閉じる