laravel-vite

Laravel のフロントエンドビルドツールとしての Vite を取り上げます。初期設定と laravel-vite-plugin、複数のエントリーポイント、CSS プリプロセッサ （Sass／Less／PostCSS）、アセットの処理、VITE_ プレフィックス付き環境変数、 開発サーバーと HMR（Docker の設定を含む）、ビルドの最適化 （チャンク分割、圧縮）、サーバーサイドレンダリング、Inertia の統合、JS フレームワーク用プラグイン（Vue／React／Svelte）、CSP nonce によるセキュリティ、そして本番環境へのデプロイを扱います。

Laravel Vite

エージェントのワークフロー（必須）

実装を始める前に、並列で 3 つのエージェントを起動してください。それぞれ name を指定して Agent を 1 回呼び出します。

1. fuse-ai-pilot:explore-codebase - 既存の vite.config.js と package.json を確認します
2. fuse-ai-pilot:research-expert - Context7 で最新の Vite ドキュメントを確認します
3. mcp__context7__query-docs - 特定のパターン（SSR、Inertia）を検索します

実装後、検証のために fuse-ai-pilot:sniper を実行してください。

---

概要

Vite は Laravel のデフォルトのフロントエンドビルドツールです。開発時には高速な HMR を提供し、本番環境向けには最適化されたビルドを生成します。

機能	目的
HMR	開発中に即座に更新
バンドル	本番環境向けにアセットを最適化
SSR	サーバーサイドレンダリングをサポート
フレームワーク	Vue、React、Svelte との統合

---

重要なルール

1. 常に laravel-vite-plugin を使用する - 生の Vite 設定は使用しないでください
2. 環境変数には VITE_ プレフィックスを付ける - フロントエンドにのみ公開されます
3. @vite ディレクティブを使用する - 手動で script タグを記述しないでください
4. デプロイ前にビルドする - CI/CD で npm run build を実行します
5. Docker 用に HMR を設定する - server.host: '0.0.0.0' を設定します

---

判断ガイド

スタックの選択

Using Tailwind CSS?
├── YES → v4? @tailwindcss/vite plugin
│         v3? PostCSS config
└── NO → Just laravel-vite-plugin

Using JavaScript framework?
├── Vue → @vitejs/plugin-vue
├── React → @vitejs/plugin-react
├── Svelte → @sveltejs/vite-plugin-svelte
└── None → Plain JS/CSS only

SSR の判断

Need SEO/fast first paint?
├── YES → Using Inertia?
│   ├── YES → Inertia SSR
│   └── NO → Consider Inertia or Livewire
└── NO → Client-side only

---

リファレンスガイド

概念（理由とアーキテクチャ）

トピック	リファレンス	参照するタイミング
セットアップ	setup.md	初期設定
エントリーポイント	entry-points.md	複数のバンドル
プリプロセッサ	preprocessors.md	Sass、Less、PostCSS
アセット	assets.md	画像、フォント、静的ファイル
環境変数	environment.md	VITE_ 変数
開発サーバー	dev-server.md	HMR、Docker、HTTPS
ビルド	build-optimization.md	チャンク、圧縮
SSR	ssr.md	サーバーサイドレンダリング
Inertia	inertia.md	API を使わない SPA
フレームワーク	frameworks.md	Vue、React、Svelte
セキュリティ	security.md	CSP nonce
デプロイ	deployment.md	本番環境、CDN

テンプレート（完全なコード）

テンプレート	使用するタイミング
ViteConfig.js.md	標準的なセットアップ
ViteConfigAdvanced.js.md	完全な最適化
InertiaSetup.md	Inertia + Vue／React
SSRSetup.md	SSR の設定

---

クイックリファレンス

基本的なセットアップ

// vite.config.js
import { defineConfig } from 'vite';
import laravel from 'laravel-vite-plugin';

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

Blade ディレクティブ

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

コマンド

コマンド	目的
npm run dev	開発サーバーを起動
npm run build	本番向けビルド
npm run preview	ビルドをプレビュー

---

ベストプラクティス

推奨事項

• Blade の HMR には refresh: true を使用します
• インポートを整理するためにエイリアスを設定します
• ベンダーを個別のチャンクに分割します
• フロントエンド用の環境変数には VITE_ プレフィックスを使用します
• Docker／Sail の設定をローカルでテストします

避けるべきこと

• VITE_ 変数を通じて機密データを公開しないでください
• デプロイ前のビルドを忘れないでください
• アセットに絶対パスを使用しないでください
• ステージング環境でソースマップを省略しないでください
• チャンクサイズの警告を無視しないでください

---

Laravel 13 の注意点

Laravel 13 のスケルトンには、laravel-vite-plugin ^3.1（現行 3.2、peer vite ^8）、Vite 8、@tailwindcss/vite ^4 が含まれています。変更点は次のとおりです。

• @vite() Blade ヘルパーはそのまま動作します
• Inertia 3 + React 19 の場合は、@vitejs/plugin-react（現行 6.x）を使用します
• セルフホスト可能なフォント（13.7+）：プラグインの fonts オプション（import { google, bunny, fontsource, local } from 'laravel-vite-plugin/fonts'）と @fonts Blade ディレクティブ
• Vite::devServerUrl()（13.31+）で開発サーバーの URL を取得します
• WebSocket 経由の HMR：開発環境では Reverb と Vite を別々のポートで共存させられます
• build.target はブラウザー（JS）のターゲットであり、サーバーの PHP バージョンとは独立しています