Laravel 9.x アセットの構築（Vite）

イントロダクションIntroduction

Viteは、非常に高速な開発環境を提供してくれる、コードを本番用に構築する最新のフロントエンド・ビルド・ツールです。Laravelでアプリケーションを構築する場合、通常、Viteを使用してアプリケーションのCSSとJavaScriptファイルを本番環境用のアセットへ構築することになります。Vite[https://vitejs.dev] is a modern frontend build tool that provides an extremely fast development environment and bundles your code for production. When building applications with Laravel, you will typically use Vite to bundle your application's CSS and JavaScript files into production ready assets.

Laravelは、開発および実働用アセットをロードするため、公式プラグインとBladeディレクティブを提供し、Viteをシームレスに統合しています。Laravel integrates seamlessly with Vite by providing an official plugin and Blade directive to load your assets for development and production.

lightbulb Note:Laravel Mixを実行していますか？新しいLaravelのインストールでは、Laravel MixをViteへ置き換えました。Mixのドキュメントは、Laravel Mixのウェブサイトをご覧ください。Viteに切り替えたい場合は、移行ガイドを参照してください。NoteAre you running Laravel Mix? Vite has replaced Laravel Mix in new Laravel installations. For Mix documentation, please visit the Laravel Mix[https://laravel-mix.com/] website. If you would like to switch to Vite, please see our migration guide[https://github.com/laravel/vite-plugin/blob/main/UPGRADE.md#migrating-from-laravel-mix-to-vite].

ViteとLaravel Mixの選択Choosing Between Vite And Laravel Mix

Viteへ移行する前、新しいLaravelアプリケーションは、アセットをバンドルする際にwebpackで動作するMixを使用していました。Viteは、リッチなJavaScriptアプリケーションを構築する際に、より速く、より生産的な体験を提供することに重点を置いています。Inertia のようなツールで開発したものを含め、シングルページアプリケーション（SPA）を開発している場合、Viteは完璧にフィットするでしょう。Before transitioning to Vite, new Laravel applications utilized Mix[https://laravel-mix.com/], which is powered by webpack[https://webpack.js.org/], when bundling assets. Vite focuses on providing a faster and more productive experience when building rich JavaScript applications. If you are developing a Single Page Application (SPA), including those developed with tools like Inertia[https://inertiajs.com], Vite will be the perfect fit.

Viteは、Livewireを使用したものを含む、JavaScriptを「ふりかけ」程度に使った従来のサーバサイドレンダリングアプリケーションでもうまく機能します。しかし、Laravel Mixがサポートしている、JavaScriptアプリケーションで直接参照されていない任意のアセットをビルドにコピーする機能など、いくつかの機能が欠落しています。Vite also works well with traditional server-side rendered applications with JavaScript "sprinkles", including those using Livewire[https://laravel-livewire.com]. However, it lacks some features that Laravel Mix supports, such as the ability to copy arbitrary assets into the build that are not referenced directly in your JavaScript application.

Mixへ戻すMigrating Back To Mix

Vite scaffoldingを使用して新しいLaravelアプリケーションを開始したが、Laravel Mixとwebpackへ戻る必要があるのですか？大丈夫です。ViteからMixへの移行に関する公式ガイドを参照してください。Have you started a new Laravel application using our Vite scaffolding but need to move back to Laravel Mix and webpack? No problem. Please consult our official guide on migrating from Vite to Mix[https://github.com/laravel/vite-plugin/blob/main/UPGRADE.md#migrating-from-vite-to-laravel-mix].

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

lightbulb Note:以下のドキュメントでは、Laravel Viteプラグインを手作業でインストールし、設定する方法について説明しています。しかし、Laravelのスターターキットには、すでにこのスカフォールドがすべて含まれており、LaravelとViteを始める最速の方法を用意しています。NoteThe following documentation discusses how to manually install and configure the Laravel Vite plugin. However, Laravel's starter kits[/docs/{{version}}/starter-kits] already include all of this scaffolding and are the fastest way to get started with Laravel and Vite.

NodeのインストールInstalling Node

ViteとLaravelプラグインを実行する前に、Node.js（１６以上）とNPMを確実にインストールしてください。You must ensure that Node.js (16+) and NPM are installed before running Vite and the Laravel plugin:

node -v
npm -v

NodeとNPMの最新版は、Node公式サイトからグラフィカルインストーラを使って簡単にインストールできます。また、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[https://laravel.com/docs/{{version}}/sail], you may invoke Node and NPM through Sail:

./vendor/bin/sail node -v
./vendor/bin/sail npm -v

ViteとLaravelプラグインのインストールInstalling Vite And The Laravel Plugin

Laravelを新規にインストールすると、アプリケーションのディレクトリ構造のルートにpackage.jsonファイルができます。デフォルトのpackage.jsonファイルは、ViteとLaravelプラグインを使い始めるために必要なものを既に含んでいます。アプリケーションのフロントエンドの依存関係は、NPM経由でインストールできます。Within a fresh installation of Laravel, you will find a package.json file in the root of your application's directory structure. The default package.json file already includes everything you need to get started using Vite and the Laravel plugin. You may install your application's frontend dependencies via NPM:

npm install

Viteの設定Configuring Vite

Viteは、プロジェクトルートのvite.config.jsファイルで設定します。また、アプリケーションが必要とする他のプラグイン、例えば、@vitejs/plugin-vueや@vitejs/plugin-reactをインストールすることもできます。Vite is configured via a vite.config.js file in the root of your project. You are free to customize this file based on your needs, and you may also install any other plugins your application requires, such as @vitejs/plugin-vue or @vitejs/plugin-react.

Laravel Viteプラグインでは、アプリケーションのエントリーポイントを指定する必要があります。これらは、JavaScriptまたはCSSファイルであり、TypeScript、JSX、TSX、Sassなどのプリプロセス言語が含まれます。The Laravel Vite plugin requires you to specify the entry points for your application. These may be JavaScript or CSS files, and include preprocessed languages such as TypeScript, JSX, TSX, and Sass.

import { defineConfig } from 'vite';
import laravel from 'laravel-vite-plugin';

export default defineConfig({
    plugins: [
        laravel([
            'resources/css/app.css',
            'resources/js/app.js',
        ]),
    ],
});

Inertiaを使用したアプリケーションを含むSPAを構築する場合、ViteはCSSエントリポイントなしで最適に動作します。If you are building an SPA, including applications built using Inertia, Vite works best without CSS entry points:

import { defineConfig } from 'vite';
import laravel from 'laravel-vite-plugin';

export default defineConfig({
    plugins: [
        laravel([
            'resources/css/app.css', // [tl! 削除]
            'resources/js/app.js',
        ]),
    ],
});

代わりに、JavaScriptでCSSをインポートする必要があります。通常、これはアプリケーションの resources/js/app.js ファイルで行います。Instead, you should import your CSS via JavaScript. Typically, this would be done in your application's resources/js/app.js file:

import './bootstrap';
import '../css/app.css'; // [tl! 追加]

また、Laravelプラグインは複数のエントリーポイントに対応し、SSRエントリーポイントなどの高度な設定オプションにも対応しています。The Laravel plugin also supports multiple entry points and advanced configuration options such as SSR entry points[#ssr].

セキュアな開発サーバの取り扱いWorking With A Secure Development Server

ローカル開発用Webサーバが、HTTPSでアプリケーションを提供している場合、Vite開発用サーバの接続に問題が発生することがあります。If your local development web server is serving your application via HTTPS, you may run into issues connecting to the Vite development server.

Laravel Valetをローカル開発に使用しており、アプリケーションでsecureコマンドを実行した場合に、Valetの生成したTLS証明書をVita開発サーバで自動的に使用するように設定できます。If you are using Laravel Valet[/docs/{{version}}/valet] for local development and have run the secure command[/docs/{{version}}/valet#securing-sites] against your application, you may configure the Vite development server to automatically use Valet's generated TLS certificates:

import { defineConfig } from 'vite';
import laravel from 'laravel-vite-plugin';

export default defineConfig({
    plugins: [
        laravel({
            // ...
            valetTls: 'my-app.test', // [tl! 追加]
        }),
    ],
});

他のWebサーバを使用する場合は、信頼できる証明書を生成し、その生成した証明書を使用するようにViteを手作業で設定する必要があります。When using another web server, you should generate a trusted certificate and manually configure Vite to use the generated certificates:

// ...
import fs from 'fs'; // [tl! 追加]

const host = 'my-app.test'; // [tl! 追加]

export default defineConfig({
    // ...
    server: { // [tl! 追加]
        host, // [tl! 追加]
        hmr: { host }, // [tl! 追加]
        https: { // [tl! 追加]
            key: fs.readFileSync(`/path/to/${host}.key`), // [tl! 追加]
            cert: fs.readFileSync(`/path/to/${host}.crt`), // [tl! 追加]
        }, // [tl! 追加]
    }, // [tl! 追加]
});

もし、あなたのシステムで信頼できる証明書を生成できない場合は、@vitejs/plugin-basic-sslプラグインをインストールし、設定してください。信頼できない証明書を使用する場合は、npm run devコマンドを実行する際にコンソールの"Local"リンクをたどり、ブラウザからVite開発サーバが出す証明書の警告を受け入れる必要があります。If you are unable to generate a trusted certificate for your system, you may install and configure the @vitejs/plugin-basic-ssl plugin[https://github.com/vitejs/vite-plugin-basic-ssl]. When using untrusted certificates, you will need to accept the certificate warning for Vite's development server in your browser by following the "Local" link in your console when running the npm run dev command.

スクリプトとスタイルの読み込みLoading Your Scripts And Styles

Viteのエントリーポイントを設定したら、アプリケーションのルートテンプレートの<head>へ追加する、@vite() Bladeディレクティブで参照するだけです。With your Vite entry points configured, you only need reference them in a @vite() Blade directive that you add to the <head> of your application's root template:

<!doctype html>
<head>
    {{-- ... --}}

    @vite(['resources/css/app.css', 'resources/js/app.js'])
</head>

JavaScriptでCSSをインポートする場合は、JavaScriptのエントリーポイントのみを記載するだけです。If you're importing your CSS via JavaScript, you only need to include the JavaScript entry point:

<!doctype html>
<head>
    {{-- ... --}}

    @vite('resources/js/app.js')
</head>

@vite ディレクティブは、Vite開発サーバを自動的に検出し、Viteクライアントを注入してホットモジュール置換を有効にします。ビルドモードでは、このディレクティブはインポートしたCSSを含む、コンパイル済みのバージョン管理しているアセットを読み込みます。The @vite directive will automatically detect the Vite development server and inject the Vite client to enable Hot Module Replacement. In build mode, the directive will load your compiled and versioned assets, including any imported CSS.

必要であれば、@viteディレクティブを呼び出す際に、コンパイル済みアセットのビルドパスを指定することもできます。If needed, you may also specify the build path of your compiled assets when invoking the @vite directive:

<!doctype html>
<head>
    {{-- 指定するビルドパスは、publicパスからの相対パス --}}

    @vite('resources/js/app.js', 'vendor/courier/build')
</head>

Viteの実行Running Vite

Viteを起動する方法は2つあります。devコマンドで開発サーバを起動するのは、ローカルで開発する際に便利です。開発サーバは、ファイルの変更を自動的に検出し、開いているブラウザウィンドウへ即座に反映させます。There are two ways you can run Vite. You may run the development server via the dev command, which is useful while developing locally. The development server will automatically detect changes to your files and instantly reflect them in any open browser windows.

もしくは、buildコマンドを実行すると、アプリケーションのアセットをバージョン付けして構築し、本番環境にデプロイできる状態にします。Or, running the build command will version and bundle your application's assets and get them ready for you to deploy to production:

# Viteを開発サーバで実行する
npm run dev

# 実働用にアセットをバンドルし、バージョン付けする
npm run build

JavaScriptの操作Working With JavaScript

エイリアスAliases

デフォルトでLaravelプラグインは、アプリケーションのアセットを便利にインポートできるように、共用エイリアスを提供します。By default, The Laravel plugin provides a common alias to help you hit the ground running and conveniently import your application's assets:

{
    '@' => '/resources/js'
}

設定ファイルvite.config.jsに独自のエイリアスを追加すれば、'@'エイリアスを上書きできます。You may overwrite the '@' alias by adding your own to the vite.config.js configuration file:

import { defineConfig } from 'vite';
import laravel from 'laravel-vite-plugin';

export default defineConfig({
    plugins: [
        laravel(['resources/ts/app.tsx']),
    ],
    resolve: {
        alias: {
            '@': '/resources/ts',
        },
    },
});

VueVue

Vueフレームワークを使用してフロントエンドを構築したい場合は、@vitejs/plugin-vueプラグインもインストールする必要があります。If you would like to build your front-end using the Vue[https://vuejs.org/] framework, then you will also need to install the @vitejs/plugin-vue plugin:

npm install --save-dev @vitejs/plugin-vue

続いて、vite.config.js設定ファイルの中で、プラグインをインクルードしてください。LaravelでVueプラグインを使用する場合、いくつかの追加オプションが必要です。You may then include the plugin in your vite.config.js configuration file. There are a few additional options you will need when using the Vue plugin with Laravel:

import { defineConfig } from 'vite';
import laravel from 'laravel-vite-plugin';
import vue from '@vitejs/plugin-vue';

export default defineConfig({
    plugins: [
        laravel(['resources/js/app.js']),
        vue({
            template: {
                transformAssetUrls: {
                    // Vueプラグインは、Single File Componentsで
                    // 参照する場合、アセットのURLをLaravelのWebサーバを
                    // 指すように書き換えます。
                    // これを`null`に設定すると、Laravelプラグインは
                    // アセットURLをViteサーバを指すように書き換えます。
                    base: null,

                    // Vueプラグインは、絶対URLを解析し、ディスク上のファイルへの
                    // 絶対パスとして扱います。
                    // これを`false`に設定すると、絶対URLはそのままになり、
                    // 期待通りにpublicディレクトリの中で、アセットへ参照できます。
                    includeAbsolute: false,
                },
            },
        }),
    ],
});

lightbulb Note:Laravelのスターターキットには、すでに適切なLaravel、Vue、Viteの構成が含まれています。Laravel、Vue、Viteを最速で使い始めるには、Laravel Breezeをチェックしてください。NoteLaravel's starter kits[/docs/{{version}}/starter-kits] already include the proper Laravel, Vue, and Vite configuration. Check out Laravel Breeze[/docs/{{version}}/starter-kits#breeze-and-inertia] for the fastest way to get started with Laravel, Vue, and Vite.

ReactReact

Reactフレームワークを使用してフロントエンドを構築したい場合、@vitejs/plugin-reactプラグインもインストールする必要があります。If you would like to build your front-end using the React[https://reactjs.org/] framework, then you will also need to install the @vitejs/plugin-react plugin:

npm install --save-dev @vitejs/plugin-react

その後、vite.config.js設定ファイル中で、プラグインをインクルードしてください。You may then include the plugin in your vite.config.js configuration file:

import { defineConfig } from 'vite';
import laravel from 'laravel-vite-plugin';
import react from '@vitejs/plugin-react';

export default defineConfig({
    plugins: [
        laravel(['resources/js/app.jsx']),
        react(),
    ],
});

JSXを含むすべてのファイルの拡張子を確実に、.jsxまたは.tsxにし、必要であれば上記のように、エントリポイントの更新を忘れないでください。You will need to ensure that any files containing JSX have a .jsx or .tsx extension, remembering to update your entry point, if required, as shown above[#configuring-vite].

更に、既存の@viteディレクティブと一緒に、追加で@viteReactRefresh Bladeディレクティブをインクルードする必要があります。You will also need to include the additional @viteReactRefresh Blade directive alongside your existing @vite directive.

@viteReactRefresh
@vite('resources/js/app.jsx')

@viteReactRefreshディレクティブは、@viteディレクティブの前に呼び出す必要があります。The @viteReactRefresh directive must be called before the @vite directive.

lightbulb Note:Laravelのスターターキットには、すでに適切なLaravel、React、Viteの設定が含まれています。Laravel、React、Viteを最速で始めるには、Laravel Breeze をチェックしてください。NoteLaravel's starter kits[/docs/{{version}}/starter-kits] already include the proper Laravel, React, and Vite configuration. Check out Laravel Breeze[/docs/{{version}}/starter-kits#breeze-and-inertia] for the fastest way to get started with Laravel, React, and Vite.

InertiaInertia

Laravel Viteプラグインは、Inertiaページコンポーネントを解決するのに便利な resolvePageComponent 関数を提供しています。以下はVue 3で使用するヘルパの例ですが、Reactなど他のフレームワークでもこの関数を利用することができます。The Laravel Vite plugin provides a convenient resolvePageComponent function to help you resolve your Inertia page components. Below is an example of the helper in use with Vue 3; however, you may also utilize the function in other frameworks such as React:

import { createApp, h } from 'vue';
import { createInertiaApp } from '@inertiajs/vue3';
import { resolvePageComponent } from 'laravel-vite-plugin/inertia-helpers';

createInertiaApp({
  resolve: (name) => resolvePageComponent(`./Pages/${name}.vue`, import.meta.glob('./Pages/**/*.vue')),
  setup({ el, App, props, plugin }) {
    return createApp({ render: () => h(App, props) })
      .use(plugin)
      .mount(el)
  },
});

lightbulb Note:Laravelのスターターキットには、すでに適切なLaravel、Inertia、Viteの構成が含まれています。Laravel、Inertia、Viteを最速で始めるには、Laravel Breeze をチェックしてください。NoteLaravel's starter kits[/docs/{{version}}/starter-kits] already include the proper Laravel, Inertia, and Vite configuration. Check out Laravel Breeze[/docs/{{version}}/starter-kits#breeze-and-inertia] for the fastest way to get started with Laravel, Inertia, and Vite.

URL処理URL Processing

Viteを使用して、アプリケーションのHTML、CSS、JSアセットを参照する場合、いくつか考慮すべき注意点があります。まず、絶対パスでアセットを参照した場合、Viteはそのアセットをビルドに含めません。したがって、そのアセットがパブリックディレクトリで利用可能であることを確認する必要があります。When using Vite and referencing assets in your application's HTML, CSS, or JS, there are a couple of caveats to consider. First, if you reference assets with an absolute path, Vite will not include the asset in the build; therefore, you should ensure that the asset is available in your public directory.

相対パスで参照する場合、参照するファイルからの相対パスであることを覚えておく必要があります。相対パスで参照されたアセットは、Viteによって書き直され、バージョン付けされ、バンドルされます。When referencing relative asset paths, you should remember that the paths are relative to the file where they are referenced. Any assets referenced via a relative path will be re-written, versioned, and bundled by Vite.

以下のようなプロジェクト構成を考えてみましょう。Consider the following project structure:

public/
  taylor.png
resources/
  js/
    Pages/
      Welcome.vue
  images/
    abigail.png

以下の例は、Viteが相対URLと絶対URLをどのように扱うかを示しています。The following example demonstrates how Vite will treat relative and absolute URLs:

<!-- このアセットをViteは扱わず、バンドルへ含まれない -->
<img src="/taylor.png">

<!-- このアセットは書き換えられ、バージョン付けし、バンドルへ含まれる -->
<img src="../../images/abigail.png">

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

ViteのCSSサポートは、Viteドキュメント で詳しく説明されています。TailwindのようなPostCSSプラグインを使用している場合、プロジェクトのルートにpostcss.config.jsファイルを作成すると、Vite が自動的にそれを適用してくれます。You can learn more about Vite's CSS support within the Vite documentation[https://vitejs.dev/guide/features.html#css]. If you are using PostCSS plugins such as Tailwind[https://tailwindcss.com], you may create a postcss.config.js file in the root of your project and Vite will automatically apply it:

module.exports = {
    plugins: {
        tailwindcss: {},
        autoprefixer: {},
    },
};

Bladeとルートの操作Working With Blade & Routes

Viteによる静的アセットの処理Processing Static Assets With Vite

JavaScriptやCSSのアセットを参照する場合、Viteは自動的に処理し、バージョン付けを行います。また、Bladeベースのアプリケーションを構築する場合、Bladeのテンプレート内だけで参照する静的なアセットもViteで処理し、バージョン付け可能です。When referencing assets in your JavaScript or CSS, Vite automatically processes and versions them. In addition, when building Blade based applications, Vite can also process and version static assets that you reference solely in Blade templates.

これを実現するには、アプリケーションのエントリポイントで静的アセットをインポートすることにより、Viteにあなたの資産を認識させる必要があります。例えば、resources/imagesに格納しているすべての画像と、resources/fontsに保存しているすべてのフォントを処理してバージョン付けする場合、アプリケーションのresources/js/app.jsエントリーポイントへ以下を追加してください。However, in order to accomplish this, you need to make Vite aware of your assets by importing the static assets into the application's entry point. For example, if you want to process and version all images stored in resources/images and all fonts stored in resources/fonts, you should add the following in your application's resources/js/app.js entry point:

import.meta.glob([
  '../images/**',
  '../fonts/**',
]);

これでnpm run buildの実行時、Viteはこれらのアセットを処理するようになります。そして、BladeテンプレートではVite::assetメソッドを使用してこれらのアセットを参照でき、指定したアセットのバージョン付けを含むURLを返します。These assets will now be processed by Vite when running npm run build. You can then reference these assets in Blade templates using the Vite::asset method, which will return the versioned URL for a given asset:

<img src="{{ Vite::asset('resources/images/logo.png') }}">

保存時の再描写Refreshing On Save

Bladeを用いる従来のサーバサイドレンダリングによりアプリケーションを構築している場合、アプリケーション内のビューファイルを変更したときに、自動でブラウザを再ロードすることにより、Viteは開発ワークフローを改善します。これを使用するには、refreshオプションをtrueへ指定するだけです。When your application is built using traditional server-side rendering with Blade, Vite can improve your development workflow by automatically refreshing the browser when you make changes to view files in your application. To get started, you can simply specify the refresh option as true.

import { defineConfig } from 'vite';
import laravel from 'laravel-vite-plugin';

export default defineConfig({
    plugins: [
        laravel({
            // ...
            refresh: true,
        }),
    ],
});

refreshオプションがtrueの場合、npm run dev実行時に以下のディレクトリへファイルを保存すると、ブラウザでページがフルリフレッシュされます。When the refresh option is true, saving files in the following directories will trigger the browser to perform a full page refresh while you are running npm run dev:

• app/View/Components/**app/View/Components/**
• lang/**lang/**
• resources/lang/**resources/lang/**
• resources/views/**resources/views/**
• routes/**routes/**

Ziggyを利用して、アプリケーションのフロントエンドでルートリンクを生成する場合、routes/**ディレクトリを監視すると便利です。Watching the routes/** directory is useful if you are utilizing Ziggy[https://github.com/tighten/ziggy] to generate route links within your application's frontend.

これらのデフォルトパスがニーズに合わない場合、監視するパスリストを独自に指定できます。If these default paths do not suit your needs, you can specify your own list of paths to watch:

import { defineConfig } from 'vite';
import laravel from 'laravel-vite-plugin';

export default defineConfig({
    plugins: [
        laravel({
            // ...
            refresh: ['resources/views/**'],
        }),
    ],
});

Laravel Viteプラグインの内部では、vite-plugin-full-reloadパッケージを使用しており、この機能の動作を微調整するために高度な設定オプションを用意しています。このレベルのカスタマイズが必要な場合は、config定義を指定してください。Under the hood, the Laravel Vite plugin uses the vite-plugin-full-reload[https://github.com/ElMassimo/vite-plugin-full-reload] package, which offers some advanced configuration options to fine-tune this feature's behavior. If you need this level of customization, you may provide a config definition:

import { defineConfig } from 'vite';
import laravel from 'laravel-vite-plugin';

export default defineConfig({
    plugins: [
        laravel({
            // ...
            refresh: [{
                paths: ['path/to/watch/**'],
                config: { delay: 300 }
            }],
        }),
    ],
});

エイリアスAliases

JavaScriptアプリケーションでは、定期的に参照するディレクトリにエイリアスを作成することが一般的です。しかし、Illuminate\Support\Facades\Viteクラスのmacroメソッドを使用して、Bladeで使用するエイリアスを作成することもできます。通常、「マクロ」は、サービスプロバイダのbootメソッド内で定義する必要があります。It is common in JavaScript applications to create aliases[#aliases] to regularly referenced directories. But, you may also create aliases to use in Blade by using the macro method on the Illuminate\Support\Facades\Vite class. Typically, "macros" should be defined within the boot method of a service provider[/docs/{{version}}/providers]:

/**
 * 全アプリケーションサービスの初期起動処理
 *
 * @return void
 */
public function boot()
{
    Vite::macro('image', fn ($asset) => $this->asset("resources/images/{$asset}"));
}

一度マクロを定義したら、テンプレート内で呼び出せます。例えば、上で定義したimageマクロを使用して、resources/images/logo.pngにあるアセットを参照してみましょう。Once a macro has been defined, it can be invoked within your templates. For example, we can use the image macro defined above to reference an asset located at resources/images/logo.png:

<img src="{{ Vite::image('logo.png') }}" alt="Laravel Logo">

ベースURLのカスタマイズCustom Base URLs

ViteでコンパイルしたアセットをCDN経由など、アプリケーションとは別のドメインにデプロイする場合は、アプリケーションの.envファイル内にASSET_URL環境変数を指定する必要があります。If your Vite compiled assets are deployed to a domain separate from your application, such as via a CDN, you must specify the ASSET_URL environment variable within your application's .env file:

ASSET_URL=https://cdn.example.com

アセットURLを設定すると、アセットを指す全ての書き換えられるURLの先頭に、設定した値が付きます。After configuring the asset URL, all re-written URLs to your assets will be prefixed with the configured value:

https://cdn.example.com/build/assets/app.9dce8d17.js

絶対URLはViteで書き直されないため、プリフィックスが付かないことを覚えておいてください。Remember that absolute URLs are not re-written by Vite[#url-processing], so they will not be prefixed.

環境変数Environment Variables

アプリケーションの.envファイルに、VITE_ というプレフィックスを付ける環境変数を設置することで、それらの環境変数をJavaScriptへ注入できます。You may inject environment variables into your JavaScript by prefixing them with VITE_ in your application's .env file:

VITE_SENTRY_DSN_PUBLIC=http://example.com

注入された環境変数は、import.meta.envオブジェクトを介してアクセスできます。You may access injected environment variables via the import.meta.env object:

import.meta.env.VITE_SENTRY_DSN_PUBLIC

テスト時のVite無効Disabling Vite In Tests

LaravelのVite統合は、テストの実行中にアセットを解決しようとするので、Vite開発サーバを実行するか、アセットをビルドする必要があります。Laravel's Vite integration will attempt to resolve your assets while running your tests, which requires you to either run the Vite development server or build your assets.

テスト中にViteをモックしたい場合は、LaravelのTestCaseクラスを拡張するすべてのテストで利用できる、withoutViteメソッドを呼び出してください。If you would prefer to mock Vite during testing, you may call the withoutVite method, which is is available for any tests that extend Laravel's TestCase class:

use Tests\TestCase;

class ExampleTest extends TestCase
{
    public function test_without_vite_example()
    {
        $this->withoutVite();

        // ...
    }
}

すべてのテストで Vite を無効にしたい場合は、ベースとなるTestCaseクラスのsetUpメソッドから、withoutViteメソッドを呼び出すとよいでしょう。If you would like to disable Vite for all tests, you may call the withoutVite method from the setUp method on your base TestCase class:

<?php

namespace Tests;

use Illuminate\Foundation\Testing\TestCase as BaseTestCase;

abstract class TestCase extends BaseTestCase
{
    use CreatesApplication;

    protected function setUp(): void// [tl! add:start]
    {
        parent::setUp();

        $this->withoutVite();
    }// [tl! add:end]
}

サーバサイドレンダリング(SSR)Server-Side Rendering (SSR)

Laravel Viteプラグインを使用すると、Viteでサーバサイドレンダリングを簡単に設定できます。まず、SSRエントリーポイントをresources/js/ssr.jsに作成し、Laravelプラグインに設定オプションを渡して、エントリーポイントを指定します。The Laravel Vite plugin makes it painless to set up server-side rendering with Vite. To get started, create an SSR entry point at resources/js/ssr.js and specify the entry point by passing a configuration option to the Laravel plugin:

import { defineConfig } from 'vite';
import laravel from 'laravel-vite-plugin';

export default defineConfig({
    plugins: [
        laravel({
            input: 'resources/js/app.js',
            ssr: 'resources/js/ssr.js',
        }),
    ],
});

SSRエントリポイントの再構築を忘れないようにするために、アプリケーションのpackage.jsonにある"build"スクリプトを拡張して、SSRビルドを作成することをお勧めします。To ensure you don't forget to rebuild the SSR entry point, we recommend augmenting the "build" script in your application's package.json to create your SSR build:

"scripts": {
     "dev": "vite",
     "build": "vite build" // [tl! 削除]
     "build": "vite build && vite build --ssr" // [tl! 追加]
}

最後に、SSRサーバの構築と起動のため、以下のコマンドを実行してください。Then, to build and start the SSR server, you may run the following commands:

npm run build
node bootstrap/ssr/ssr.mjs

lightbulb Note:Laravelのスターターキットには、すでに適切なLaravel、Inertia SSR、Viteの構成が含まれています。Laravel、Inertia SSR、Viteを最速で使い始めるため、Laravel Breeze をチェックしてください。NoteLaravel's starter kits[/docs/{{version}}/starter-kits] already include the proper Laravel, Inertia SSR, and Vite configuration. Check out Laravel Breeze[/docs/{{version}}/starter-kits#breeze-and-inertia] for the fastest way to get started with Laravel, Inertia SSR, and Vite.

Scriptとstyleタグ属性Script & Style Tag Attributes

コンテンツセキュリティポリシー（CSP）ノンスContent Security Policy (CSP) Nonce

コンテンツセキュリティポリシーの一環として、スクリプトやスタイルタグに、nonce属性を含めたい場合は、カスタムミドルウェアのuseCspNonceメソッドを使用して、ノンスを生成・指定できます。If you wish to include a nonce attribute[https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/nonce] on your script and style tags as part of your Content Security Policy[https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP], you may generate or specify a nonce using the useCspNonce method within a custom middleware[/docs/{{version}}/middleware]:

<?php

namespace App\Http\Middleware;

use Closure;
use Illuminate\Support\Facades\Vite;

class AddContentSecurityPolicyHeaders
{
    /**
     * 受診リクエストの処理
     *
     * @param  \Illuminate\Http\Request  $request
     * @param  \Closure  $next
     * @return mixed
     */
    public function handle($request, Closure $next)
    {
        Vite::useCspNonce();

        return $next($request)->withHeaders([
            'Content-Security-Policy' => "script-src 'nonce-".Vite::cspNonce()."'",
        ]);
    }
}

useCspNonceメソッドが呼び出だされると、Laravelは生成するすべてのscriptタグとstyleタグへ、nonce属性を自動的に含めます。After invoking the useCspNonce method, Laravel will automatically include the nonce attributes on all generated script and style tags.

Laravelのスターターキットに含まれるZiggy @route directiveなど、別の場所でノンスを指定する必要がある場合、cspNonceメソッドを使用して取得できます。If you need to specify the nonce elsewhere, including the Ziggy @route directive[https://github.com/tighten/ziggy#using-routes-with-a-content-security-policy] included with Laravel's starter kits[/docs/{{version}}/starter-kits], you may retrieve it using the cspNonce method:

@routes(nonce: Vite::cspNonce())

Laravelに使わせたいノンスが既にある場合は、useCspNonceメソッドへ、そのノンスを渡してください。If you already have a nonce that you would like to instruct Laravel to use, you may pass the nonce to the useCspNonce method:

Vite::useCspNonce($nonce);

サブリソース完全性（SRI）Subresource Integrity (SRI)

Viteマニフェストにアセット用のintegrityハッシュが含まれている場合、Laravelは自動的にintegrity属性を生成するスクリプトとスタイルタグに追加し、サブリソース完全性を強要します。Viteはデフォルトでは、integrityハッシュをマニフェストに含みませんが、 vite-plugin-manifest-sri NPMプラグインをインストールすれば、これを有効にできます。If your Vite manifest includes integrity hashes for your assets, Laravel will automatically add the integrity attribute on any script and style tags it generates in order to enforce Subresource Integrity[https://developer.mozilla.org/en-US/docs/Web/Security/Subresource_Integrity]. By default, Vite does not include the integrity hash in its manifest, but you may enable it by installing the vite-plugin-manifest-sri[https://www.npmjs.com/package/vite-plugin-manifest-sri] NPM plugin:

npm install --save-dev vite-plugin-manifest-sri

このプラグインは、vite.config.jsファイルで有効にします。You may then enable this plugin in your vite.config.js file:

import { defineConfig } from 'vite';
import laravel from 'laravel-vite-plugin';
import manifestSRI from 'vite-plugin-manifest-sri';// [tl! 追加]

export default defineConfig({
    plugins: [
        laravel({
            // ...
        }),
        manifestSRI(),// [tl! 追加]
    ],
});

必要であれば、完全性ハッシュを見つけることができるマニフェスト・キーもカスタマイズできます。If required, you may also customize the manifest key where the integrity hash can be found:

use Illuminate\Support\Facades\Vite;

Vite::useIntegrityKey('custom-integrity-key');

この自動検出を完全に無効にする場合は、useIntegrityKeyメソッドへfalseを渡します。If you would like to disable this auto-detection completely, you may pass false to the useIntegrityKey method:

Vite::useIntegrityKey(false);

任意の属性Arbitrary Attributes

もし、スクリプトタグやスタイルタグに追加の属性、例えば data-turbo-track属性を含める必要がある場合は、useScriptTagAttributesとuseStyleTagAttributesメソッドで指定できます。通常、このメソッドは サービスプロバイダから呼び出す必要があります。If you need to include additional attributes on your script and style tags, such as the data-turbo-track[https://turbo.hotwired.dev/handbook/drive#reloading-when-assets-change] attribute, you may specify them via the useScriptTagAttributes and useStyleTagAttributes methods. Typically, this methods should be invoked from a service provider[/docs/{{version}}/providers]:

use Illuminate\Support\Facades\Vite;

Vite::useScriptTagAttributes([
    'data-turbo-track' => 'reload', // 属性の値を指定
    'async' => true, // 値を指定しない属性
    'integrity' => false, // 本来含まれる属性を除外
]);

Vite::useStyleTagAttributes([
    'data-turbo-track' => 'reload',
]);

条件付きで属性を追加する必要がある場合、アセットのソースパスとそのURL、マニフェストのチャンク、およびマニフェスト全体を受け取るコールバックを渡してください。If you need to conditionally add attributes, you may pass a callback that will receive the asset source path, its URL, its manifest chunk, and the entire manifest:

use Illuminate\Support\Facades\Vite;

Vite::useScriptTagAttributes(fn (string $src, string $url, array|null $chunk, array|null $manifest) => [
    'data-turbo-track' => $src === 'resources/js/app.js' ? 'reload' : false,
]);

Vite::useStyleTagAttributes(fn (string $src, string $url, array|null $chunk, array|null $manifest) => [
    'data-turbo-track' => $chunk && $chunk['isEntry'] ? 'reload' : false,
]);

warning Warning! Vite開発サーバが起動している間は、$chunkと$manifest引数は、nullになります。WarningThe $chunk and $manifest arguments will be null while the Vite development server is running.

高度なカスタマイズAdvanced Customization

LaravelのViteプラグインは、ほとんどのアプリケーションで動作するように、合理的な規約をはじめから使用しています。しかし、時にはViteの動作をカスタマイズする必要が起きるかもしれません。追加のカスタマイズオプションを有効にするための、@vite Bladeディレクティブの代わりに使用可能な、以下のメソッドとオプションを提供しています。Out of the box, Laravel's Vite plugin uses sensible conventions that should work for the majority of applications; however, sometimes you may need to customize Vite's behavior. To enable additional customization options, we offer the following methods and options which can be used in place of the @vite Blade directive:

<!doctype html>
<head>
    {{-- ... --}}

    {{
        Vite::useHotFile(storage_path('vite.hot')) // 「ホット」なファイルのカスタマイズ
            ->useBuildDirectory('bundle') // ビルドディレクトリのカスタマイズ
            ->useManifestFilename('assets.json') // マニフェストファイル名のカスタマイズ
            ->withEntryPoints(['resources/js/app.js']) // エントリポイントの指定
    }}
</head>

そして、vite.config.jsファイル内でも、同じ設定を指定する必要があります。Within the vite.config.js file, you should then specify the same configuration:

import { defineConfig } from 'vite';
import laravel from 'laravel-vite-plugin';

export default defineConfig({
    plugins: [
        laravel({
            hotFile: 'storage/vite.hot', // 「ホット」なファイルのカスタマイズ
            buildDirectory: 'bundle', // ビルドディレクトリのカスタマイズ
            input: ['resources/js/app.js'], // エントリポイントの指定
        }),
    ],
    build: {
      manifest: 'assets.json', // マニフェストファイル名のカスタマイズ
    },
});

開発サーバURLの修正Correcting Dev Server URLs

Viteエコシステム内のプラグインのいくつかは、フォワードスラッシュで始まるURLを常にVite開発サーバを指すと仮定しています。しかし、Laravelとの統合の関係上、これは好ましくありません。Some plugins within the Vite ecosystem assume that URLs which begin with a forward-slash will always point to the Vite dev server. However, due to the nature of the Laravel integration, this is not the case.

例えば、vite-imagetoolsプラグインは、Viteがあなたのリソースを提供しているとき、以下のようなURLを出力します。For example, the vite-imagetools plugin outputs URLs like the following while Vite is serving your assets:

<img src="/@imagetools/f0b2f404b13f052c604e632f2fb60381bf61a520">

vite-imagetoolsプラグインは、Viteが出力するURLを傍受し、このプラグインが/@imagetoolsで始まるすべての URLを処理すると仮定しています。このような挙動を期待するプラグインを使用している場合、手作業でURLを修正する必要があります。これは、vite.config.jsファイルのtransformOnServeオプションを使用して行います。The vite-imagetools plugin is expecting that the output URL will be intercepted by Vite and the plugin may then handle all URLs that start with /@imagetools. If you are using plugins that are expecting this behaviour, you will need to manually correct the URLs. You can do this in your vite.config.js file by using the transformOnServe option.

この例は、生成されたコード内で、/@imagetoolsの全出現箇所に、開発サーバのURLを追加します。In this particular example, we will append the dev server URL to all occurrences of /@imagetools within the generated code:

import { defineConfig } from 'vite';
import laravel from 'laravel-vite-plugin';
import { imagetools } from 'vite-imagetools';

export default defineConfig({
    plugins: [
        laravel({
            // ...
            transformOnServe: (code, devServerUrl) => code.replaceAll('/@imagetools', devServerUrl+'/@imagetools'),
        }),
        imagetools(),
    ],
});

これで、Viteがアセットを配信する間、Viteの開発サーバを指すURLが出力されます。Now, while Vite is serving Assets, it will output URLs that point to the Vite dev server:

- <img src="/@imagetools/f0b2f404b13f052c604e632f2fb60381bf61a520"><!-- [tl! remove] -->
+ <img src="http://[::1]:5173/@imagetools/f0b2f404b13f052c604e632f2fb60381bf61a520"><!-- [tl! add] -->