Laravel Viteとは、フロントエンドのビルドツールViteを、公式プラグイン laravel-vite-plugin とBladeの @vite ディレクティブでLaravelにつないだ構成のことです。新規のLaravelではこれが標準で入っています。この記事では、2026年10月16日に作成したLaravel 13.37.0のプロジェクトで、@vite が実際に出力するHTML、開発サーバの起動方法、フォントの扱い、本番で画面が崩れる原因を確かめた結果を整理します。
まとめ
- Laravel Viteは、Vite（ビルドと開発サーバ）、
laravel-vite-plugin（Laravel向けの設定）、@vite（Bladeでの読み込み）の3つで動きます。2026年10月時点の現行版はVite 8.3.4とlaravel-vite-plugin 3.2.0で、ViteのNode.js要件は20系の20.19.0以上、または22.12.0以上です。macOSやLinuxで現行の開発一括起動を使う場合は、後述するmultiplexの要件も確認してください。 @viteは<head>に1回だけ書きます。public/hotがあれば開発サーバのURLを、無ければpublic/build/manifest.jsonを見てビルド済みファイルのURLを出力します。- Laravel 13の現行スケルトンでは、
composer run devの中身がphp artisan devに変わりました。サーバ・キュー・ログ・Viteの4つを同時に起動します。ブラウザで開くのはアプリのURLで、5173番ではありません。 - スケルトンの
vite.config.jsにはfontsオプション（Bunny FontsのInstrument Sans）が最初から入っています。ビルド時にフォントを取得するため、CIから外部へ接続できない環境では設定を見直します。 - 本番でCSSやJSが読み込まれないときは、まず次の2点を確認します。
manifest.jsonが無い（ビルド漏れ）か、強制終了したViteのpublic/hotが残っているかです。 - Laravel Mixは公式に「積極的にメンテナンスされていないレガシーパッケージ」とされています。新規に選ぶ理由はありません。
Laravel Viteの構成要素と現行バージョン
Vite・laravel-vite-plugin・@viteの役割分担
Viteは、ブラウザへ配信するCSSとJavaScriptをまとめるツールです。PHPのソースには触れません。laravel-vite-plugin はViteの設定にLaravel向けの既定値を足します。たとえば出力先 public/build、@ エイリアス、Blade保存時の再読み込みです。Laravel本体の Illuminate\Foundation\Vite クラスは @vite の裏側にあり、開発中か本番かを判定して、出力する <script> と <link> を切り替えます。
「PHPでViteは使えるのか」という疑問には、この分担がそのまま答えになります。Viteが動くのはNode.js側だけです。PHPの実行環境は変わりません。Laravelは、Viteが出力したファイルの場所を読んでHTMLに書き込む役割だけを持ちます。
標準化の版境界と2026年10月時点の現行版
LaravelがMixからViteへ切り替えたのは laravel/framework 9.19.0です。2026年10月16日時点の現行版は次のとおりです（npm registryの dist-tags.latest と各リポジトリのCHANGELOGで確認）。
| パッケージ | 現行版 | 要点 |
|---|---|---|
| vite | 8.3.4 | Node ^20.19.0 || >=22.12.0 |
| laravel-vite-plugin | 3.2.0（2026-08-11） | peerはvite ^8.0.0 |
| laravel/framework | 13.37.0（2026-10-16） | @fontsは13.7.0で追加 |
| laravel-mix | 6.0.49（2022-06） | 公式がレガシー扱い |
laravel-vite-pluginのCHANGELOGによると、3.0.0（2026-03-18）でVite 8に対応しました。package.json の peerDependencies は vite: ^8.0.0 です。Vite 7以前のままプラグインだけを3系に上げると、npm 7以降では ERESOLVE でインストールが止まります。プラグインとViteは一緒に上げてください。
Laravel Mixに対する公式の位置づけ
Laravel 13のMixのドキュメントは、冒頭で “Laravel Mix is a legacy package that is no longer actively maintained.” と書いています。続く段落には “Vite has replaced Laravel Mix in new Laravel installations.” ともあります。npmへの最終公開は2022年6月です。既存プロジェクトのMixがすぐ壊れるわけではありませんが、新規に採用するものではありません。
@viteが開発時と本番時に出力するHTML
Laravel Viteの仕組みは、@vite が出力するHTMLを見るのがいちばん早く理解できます。次のBladeを置いて、両方のモードの出力を取得しました。
<head>
@fonts
@vite(['resources/css/app.css', 'resources/js/app.js'])
</head>npm run dev の実行中は、プラグインが public/hot に開発サーバのURLを書き込みます。今回は http://[::1]:5173 でした。Laravelはこのファイルを見つけると、開発サーバを指すタグを出力します。
<script type="module" src="http://[::1]:5173/@vite/client"></script>
<link rel="stylesheet" href="http://[::1]:5173/resources/css/app.css" />
<script type="module" src="http://[::1]:5173/resources/js/app.js"></script>@vite/client はHMR（ページを再読み込みせずに変更を反映する仕組み）用のクライアントです。public/hot が無いときは、public/build/manifest.json からハッシュ付きのファイル名を引いて出力します。preload と modulepreload も自動で付きます。
<link rel="preload" as="style" href="http://127.0.0.1:18751/build/assets/app-6jSCucsl.css" />
<link rel="modulepreload" as="script" href="http://127.0.0.1:18751/build/assets/app-BvRk9kiK.js" />
<link rel="stylesheet" href="http://127.0.0.1:18751/build/assets/app-6jSCucsl.css" />
<script type="module" src="http://127.0.0.1:18751/build/assets/app-BvRk9kiK.js"></script>つまり、モードを決めているのは APP_ENV ではなく public/hot があるかどうかです。この点を押さえておくと、後で触れる本番の白画面の原因がすぐ分かります。@vite を <head> と <body> の両方に書くと、同じタグが2組出力されるだけで何も良くなりません。書くのは1か所です。
Laravel 13の初期構成とvite.config.jsの読み方
インストール手順とNode.jsの実際の要件
composer create-project laravel/laravel やスターターキットで作ったプロジェクトには、package.json と vite.config.js が最初から入っています。npm install を実行するだけです。既存プロジェクトに後から入れる場合は次のとおりです。
npm install --save-dev vite laravel-vite-plugin
npm pkg set type="module"Laravel 13の公式ドキュメントは、今も “Node.js (16+)” と書いています。ただし、laravel-vite-plugin 3.2.0とVite 8.3.4は、どちらも engines に ^20.19.0 || >=22.12.0 を宣言しています。Vite単体の実行環境はこの範囲に合わせます。ただし、macOSやLinuxで現行の composer run dev を使う場合は、起動に使われる @laravel/multiplex の要件も満たすNode.js 22.13.0以上が必要です。
スケルトンのvite.config.jsに入っている設定
2026年10月時点のスケルトンの vite.config.js は次のとおりです。
import { defineConfig } from 'vite';
import laravel from 'laravel-vite-plugin';
import { bunny } from 'laravel-vite-plugin/fonts';
import tailwindcss from '@tailwindcss/vite';
export default defineConfig({
plugins: [
laravel({
input: ['resources/css/app.css', 'resources/js/app.js'],
refresh: true,
fonts: [
bunny('Instrument Sans', {
weights: [400, 500, 600],
}),
],
}),
tailwindcss(),
],
server: {
watch: {
ignored: ['**/storage/framework/views/**'],
},
},
});input はエントリポイントで、指定は必須です。refresh: true を指定すると、app/Livewire、app/View/Components、lang、resources/lang、resources/views、routes のうち存在するディレクトリが監視対象になり、保存するとブラウザ全体が再読み込みされます（プラグイン3.2.0のソースで確認）。server.watch.ignored は、Bladeのコンパイル結果が置かれる storage/framework/views をViteの監視から外す指定です。CSSはTailwind CSS v4の @tailwindcss/vite で処理されるため、tailwind.config.js と postcss.config.js はありません。
SPAのエントリポイントと@エイリアス
InertiaなどのSPAでは、公式は「CSSのエントリポイントを持たない構成が最も良く動く」としています。resources/js/app.js の中で import '../css/app.css'; と書き、input と @vite にはJSだけを渡してください。Inertiaの仕組みと3系の変更点はLaravel Inertiaとは｜APIを作らずSPAを組む仕組みと3系の変更点で扱っています。
プラグインは @ を /resources/js に向けるエイリアスを自動で追加します。別の場所に置きたいときだけ resolve.alias で上書きします。Mixから移行する場合、エイリアスのパスは /resources/js のようにスラッシュから始めてください。
開発サーバの起動とアクセス先
composer run devからphp artisan devへの起動処理の変更
現行スケルトンの composer.json では、dev スクリプトの中身が @php artisan dev です。laravel/frameworkのCHANGELOGによると、artisan dev コマンドは13.16.0（2026-06-16）で追加されました。13.25.0（2026-08-11）からは、npmパッケージの @laravel/multiplex を通して起動します。起動する内容は php artisan dev:list で確認できます。
php artisan dev:list
server php artisan serve
queue php artisan queue:listen --tries=1 --timeout=0
logs php artisan pail --timeout=0
vite npm run devDevCommandのソースでは、Windowsでは従来どおり concurrently を使い、それ以外のOSでは @laravel/multiplex を使うよう分岐しています。--tabs、--stream、--inline で表示形式を選べます。Laravel 11や12で作ったプロジェクトの composer.json には concurrently を直接呼ぶ古い定義が残っていますが、そのままでも動きます。Viteだけ動かしたいなら、これまでどおり npm run dev を使えます。
5173番を直接開いたときの案内ページとポート固定
Viteの開発サーバは既定でポート5173を使います。ブラウザで開くのはLaravelアプリのURLです（php artisan serve なら8000番、Herdなら .test のホスト名）。http://localhost:5173/ を直接開くと、プラグイン同梱の dev-server-index.html が返ります。今回の実測ではステータスは404でしたが、タイトルが「Laravel Vite」のページに .env の APP_URL（http://localhost:8000）が表示され、開き直す先が分かるようになっていました。
5173番が使用中だと、Viteは5174番以降へ自動で移ります。番号を固定したい場合は server.strictPort: true を指定します。この場合、使用中なら起動せずに終了します（Viteのserverオプション）。HerdやSailの使い分けはLaravel Herdとは｜PHPバージョン切替と.test公開の仕組み・Sailとの使い分けにまとめています。
fontsオプションと静的アセットの扱い
fontsオプションと@fontsディレクティブ
フォントの最適化機能は、laravel-vite-plugin 3.0系とLaravel 13.7.0（2026年4月末）で追加されました。laravel-vite-plugin/fonts から google、bunny、fontsource、local のいずれかを読み込み、fonts に渡します。Blade側では @fonts と書くだけです。スケルトンの設定で npm run build を実行すると、ウェイト400・500・600のwoff2とwoffが合わせて6ファイル、さらに fonts-manifest.json が public/build に出力されました。本番の @fonts は、woff2の3ファイル分の <link rel="preload" as="font"> と、@font-face を含む <style> を出力します。
知らないと戸惑う点が2つあります。1つ目は、スケルトンのまま npm run dev を実行すると次の警告が出ることです。
[laravel:fonts] Optimized font fallbacks require the optional "fontaine" package. Install it, or set "optimizedFallbacks: false" on your fonts to disable the feature.公式ドキュメントのとおり、optimizedFallbacks の既定は true ですが、fontaine は既定ではインストールされません。警告を消すには、npm install --save-dev fontaine を実行するか、フォント定義に optimizedFallbacks: false を足します。2つ目は、フォントをビルド時に fonts.bunny.net から取得し、node_modules/.cache/laravel-vite-plugin/fonts にキャッシュすることです。取得に失敗すると、プラグインは Failed to fetch でビルドを止めます。外部へ接続できないCIでは、local() で resources/fonts のファイルを使うように切り替えるのが確実です。
Blade専用画像のassets指定とVite::assetによる参照
Bladeからしか参照しない画像は、JavaScriptからimportされないため、Viteはその存在を知りません。プラグイン3系では assets オプションで対象を宣言します。
laravel({
input: 'resources/js/app.js',
assets: ['resources/images/**'],
})Blade側では Vite::asset('resources/images/logo.png') でバージョン付きのURLを取得します。UPGRADE.mdは、2系で import.meta.glob を使って画像をビルドに含めていた場合、assets へ移す必要があると説明しています。フォントのCSSとpreloadを生成したい場合は、assets ではなく前の節の fonts を使います。
VueとReactを組み合わせるときの追加設定
VueのtransformAssetUrlsとBladeへの部分マウント
Vueを使うときは、npm install --save-dev @vitejs/plugin-vue を実行し、次の2つのオプションを付けます。
vue({
template: {
transformAssetUrls: {
base: null,
includeAbsolute: false,
},
},
}),base: null は、単一ファイルコンポーネント内のアセットURLの書き換えをLaravel側のプラグインに任せる指定です。includeAbsolute: false は、/images/logo.png のような絶対パスを書き換えずに残し、public 配下を参照できるようにします。
Bladeの一部にだけVueを埋め込み、テンプレートをBladeのHTMLに直接書く場合は、もう1つ設定が必要です。ビルドツールが既定で使うVueのランタイム専用ビルドには、テンプレートのコンパイラが含まれていません。Vue公式のツールガイドのとおり、resolve.alias で vue を vue/dist/vue.esm-bundler.js に向けます。Vue公式が示すコンパイラ分の差は、minify・gzip圧縮後で約14KBです。.vue ファイルだけで組めるなら、この設定は不要です。
Reactプラグインの選び方
Reactは @vitejs/plugin-react を追加し、laravel() と並べて設定します。JSXを含むファイルは拡張子を .jsx または .tsx にし、エントリポイントも合わせます。Bladeでは @vite の前に @viteReactRefresh を記述します。プラグインのv6ではBabelが外れるなど変更が続いているため、選び方は@vitejs/plugin-react とは？v6（Vite 8・Babel廃止）の導入設定と plugin-react-swc との違いを確認してください。Inertiaで一体化するか、APIとSPAに分けるかの判断はLaravelとReactの連携方法｜3つの構成の選び方とInertia・Sanctumの設定【Laravel 13】にあります。
本番ビルドとデプロイで壊れる典型パターン
npm run buildの出力物とmanifest.jsonの実パス
スケルトンで npm run build を実行すると、1.83秒で public/build/manifest.json、fonts-manifest.json、assets/ 配下のCSS・JS・フォント9ファイルが出力されました。ビルドディレクトリ build とマニフェスト名 manifest.json は、Illuminate\Foundation\Vite の既定値です。public/build は通常 .gitignore に入っています。リポジトリを配置するだけのデプロイでは、デプロイ先でビルドするか、成果物を転送する工程を入れてください。デプロイ時のキャッシュ再生成の順序はLaravelのキャッシュクリア｜cache:clearとoptimize:clearの違いと本番デプロイの手順にまとめています。
Vite manifest not foundと標準welcomeビューの回避処理
マニフェストを退避して自作のビューを開くと、HTTP 500で次の例外になりました。
Illuminate\Foundation\ViteManifestNotFoundException
Vite manifest not found at: /private/tmp/lab3251/app/public/build/manifest.json一方、同じ状態でもトップの welcome.blade.php は200で表示されました。スケルトンのこのビューは、@if (file_exists(public_path('build/manifest.json')) || file_exists(public_path('hot'))) で囲まれていて、ファイルが無ければインラインのCSSに切り替わるからです。「初期画面は出るのに、自分で作った画面だけ500になる」場合は、ビルドしていないことを最初に疑ってください。エラーに表示されたパスにファイルがあれば、次は実行ユーザの読み取り権限を確認します。ViteManifestNotFoundException は @deprecated use ViteException とされているので、例外を捕捉するコードは ViteException 側に寄せます。
public/hotの残留による白画面
public/hot があるあいだ、@vite は本番でも開発サーバのURLを出力します。Viteを SIGTERM で止めた場合は、プラグインが hot を削除しました。ソース上は、Ctrl+C（SIGINT）と SIGHUP も同じ削除処理を通ります。SIGKILL で強制終了した場合は残り、Bladeは止まっている http://[::1]:5173 を指し続けました。開発機の public をそのまま同期するデプロイでは、この状態が本番に持ち込まれます。デプロイ手順に削除を入れておいてください。
rm -f public/hotCDN配信時のASSET_URL
ビルド成果物を別ドメインから配信する場合は、.env に ASSET_URL を設定します。ASSET_URL=https://cdn.example.com で出力を確認すると、src="https://cdn.example.com/build/assets/app-BvRk9kiK.js" になりました。ソース中に絶対URLで書いたパスはViteが書き換えないため、この前置きも付きません。
SSR・テスト・タグ属性の設定
SSRエントリポイントとInertiaのSSRサーバ
SSRでは、laravel({ input: 'resources/js/app.js', ssr: 'resources/js/ssr.js' }) のようにSSR用のエントリを渡し、ビルドスクリプトを "build": "vite build && vite build --ssr" にします。Inertiaを使う場合は、Node側のサーバを自分で書く必要はなく、php artisan inertia:start-ssr で用意されたSSRサーバを起動できます。Inertia SSRの設定はスターターキットに最初から入っています。キットの選び方はLaravel Breezeはなぜ非推奨に？Laravel 13のスターターキット4種と移行判断を参照してください。
テストでViteを無効化するwithoutVite
FeatureテストでBladeを描画すると、ビルドしていないCIでは前述のマニフェストの例外が出ます。テスト内で $this->withoutVite(); を呼べば、アセットの解決を省略できます。全テストで省略したいなら、基底の TestCase の setUp に書きます。フロント側のユニットテストをVitestで書いている場合はVitest 5移行ガイドを参照してください。
prefetchとCSP nonce
コード分割したSPAでは、画面遷移のたびに必要なチャンクを取得するため、描画が遅れることがあります。AppServiceProvider の boot で Vite::prefetch(concurrency: 3); を呼ぶと、初回表示の後に最大3件の同時ダウンロードで対象のJSとCSSを先読みします。既定では load イベントで始まります。
Content Security Policyでスクリプトを制限している場合は、ミドルウェアで Vite::useCspNonce() を呼びます。生成したnonceが @vite の出力するタグに付きます。CSPヘッダには Vite::cspNonce() で同じ値を渡してください。どちらのメソッドもLaravel 13のViteクラスに実在します。
SailやDockerでHMRが効かないときの設定
hotファイルのホストが決まる順序
コンテナ内でViteを動かすと、ブラウザが public/hot に書かれたホストへ接続できず、HMRが効かないことがあります。プラグイン3.2.0では、server.origin を指定すると、そのURLを基に hot が生成されます。未指定のときは、server.hmr.host、Sail実行時の localhost、server.host、Viteが実際にlistenしたアドレスの順でホストが決まります。Sail用の localhost が使われるのは、server.host を自分で指定していない場合だけです。実測すると、npx vite --host 0.0.0.0 では http://0.0.0.0:5173 に、環境変数 LARAVEL_SAIL=1 を付けると http://localhost:5173 になりました。
Sailでは、プラグインが host: '0.0.0.0'、VITE_PORT（既定5173）、strictPort: true を自動で設定します。追加の設定は基本的に不要です（WSL2で接続できない場合は、公式どおり hmr.host を指定します）。Sailを使わない自前のDocker構成では、自分で3つの設定をします。
server: {
host: '0.0.0.0',
port: 5173,
strictPort: true,
hmr: {
host: 'localhost',
},
},あわせて、docker-compose.yml の ports に "5173:5173" を追加します。hmr.host が無いと hot が 0.0.0.0 を指してしまい、接続先として扱えないブラウザがあります。
ファイル変更が検知されないときのポーリング
ホストOS側で保存しても反映されない場合は、コンテナのファイル監視が変更を拾えていません。server.watch.usePolling: true を指定してください。ポーリングは常にファイルを走査するので、CPU使用率が上がります。スケルトンの ignored に **/vendor/** などを足し、監視対象を絞ってから使います。
Laravel MixからViteへ移行する手順と判断基準
Mixとの対応表
| 項目 | Laravel Mix | Vite |
|---|---|---|
| 設定ファイル | webpack.mix.js | vite.config.js |
| Bladeでの読み込み | mix(‘js/app.js’) | @vite([…]) |
| マニフェスト | public/mix-manifest.json | public/build/manifest.json |
| 環境変数 | MIX_ / process.env | VITE_ / import.meta.env |
| アプリ側のモジュール記法 | require可 | importへ移行 |
| 開発時 | npm run watch | npm run dev（開発サーバ） |
手順は公式の移行ガイドのとおりです。package.json のscriptsを "dev": "vite" と "build": "vite build" に置き換え、require() を import に書き換えます。作業の中心はこの書き換えです。ガイド自身が冒頭で、Sassのコンパイルなど、Mixの使い方をすべては網羅していないと断っています。Mix独自のメソッドで組んだ処理は、Vite側で組み直すつもりで見積もってください。
移行で出やすいエラーと対処
"laravel-vite-plugin" resolved to an ESM file：package.jsonに"type": "module"がありません。npm pkg set type="module"で追加します。- その後に古い設定ファイルが読めなくなる：
module.exportsで書いたtailwind.config.jsなどは、拡張子を.cjsに変えるかexport defaultに書き換えます。 npm installがERESOLVEで止まる：古い@types/nodeやVite 7以前がpeer指定とぶつかっています。npm ls viteで依存元を確かめ、該当パッケージを上げます。
移行を急がなくてよい条件
稼働中のプロジェクトでMixが問題なく動いていて、フロントの変更が少ないなら、すぐに移行しなくてもかまいません。require() の書き換えは、コードが大きいほど回帰の範囲が広がります。逆に、Node.jsを上げたらwebpackまわりのビルドが通らなくなった、という状況になってからでは遅いです。修復と移行を同時に進めることになるので、その前に移してください。業務システムでフロントのビルド基盤を含めて作り直す場合は、フルスクラッチ開発で構成から相談を受けています。
よくある質問
Vite+とLaravel Viteは同じものですか？
別物です。Laravelが標準で入れるのは、Vite本体と laravel-vite-plugin です。Vite+はVite 8の上にテスト・lint・フォーマットをまとめた vp コマンドの層で、Laravelのスケルトンには含まれていません。中身と移行手順はVite+とは？vpコマンドの使い方と1.0の中身・既存Vite案件の移行手順を実装目線で解説にまとめています。
ビルドの出力先をpublic/build以外に変えられますか？
変えられます。laravel({ input: 'resources/js/app.js', buildDirectory: 'bundle' }) と指定し、Blade側は @vite('resources/js/app.js', 'bundle') のように第2引数でそろえます。アプリ全体で変える場合は、Vite::useBuildDirectory('bundle') をサービスプロバイダで呼ぶ方法もあります。build.outDir を直接書き換えると、Laravel側がマニフェストを見つけられなくなります。
.envの値をJavaScript側から読めますか？
既定の設定でクライアント側へ公開されるのは、接頭辞が VITE_ の環境変数です。import.meta.env.VITE_APP_NAME の形で参照します。ビルド結果にそのまま埋め込まれ、ブラウザから見えるので、APIキーなどの秘密情報を入れてはいけません。
Viteの開発サーバのポートを5173に固定できますか？
固定できます。server.strictPort: true にすると、5173が使用中のときに別のポートへ移らず終了します。Sail上では、プラグインが最初から strictPort: true にしています。
本番環境でもnpm run devを動かす必要がありますか？
必要ありません。本番に必要なのは、npm run build が生成した public/build 配下のファイルだけです。本番で開発サーバを動かすと public/hot が作られ、利用者のブラウザが開発サーバのURLを読みに行ってしまいます。Laravel本体のバージョンとサポート期限はLaravelの最新バージョンは13｜対応PHPバージョン・サポート期限一覧とアップグレード判断で確認できます。
