Laravel Vite Laravel Package

Getting Started

• Check compatibility first. The package is archived (last release Feb 2023) and in maintenance mode. Confirm it works with your Laravel, PHP, and Vite versions before adopting it. On any modern Laravel (9.19+), the framework already ships a first-party @vite directive and the laravel-vite-plugin npm package, so this library is only worth using if you're on an older stack or already depend on its config format.
• Install the package with Composer, then publish its config:

  composer require innocenzi/laravel-vite
  php artisan vendor:publish   # pick the Vite config entry/tag for your version
  

• Look first at config/vite.php. This is the source of truth for the package. The important keys are the entrypoint map, the hot file location (public/hot by default), the build directory (public/build), the manifest path, and the dev server URL. Get these aligned with vite.config.js before debugging anything else.
• Configure Vite to emit a manifest — the package reads it in production:

  // vite.config.js
  export default defineConfig({
    build: {
      manifest: true,
      outDir: 'public/build',
      rollupOptions: {
        input: ['resources/js/app.ts', 'resources/css/app.css'],
      },
    },
  });
  

• Wire it into Blade. Replace manual <script>/<link> tags with the directive:

  @vite(['resources/js/app.ts', 'resources/css/app.css'])
  

  Depending on your config, you may also reference a named entrypoint declared under entrypoints (e.g. @vite('app')).
• First use case: a single-page Blade layout that currently hardcodes <script src="/js/app.js">. Point the directive at your real entrypoint, run npm run dev, and confirm the page loads modules from the Vite dev server. Then run npm run build and confirm it switches to hashed files from the manifest.

Implementation Patterns

• One directive per layout, many entrypoints. Pass an array in the order you want them injected. Keep the list identical to the rollupOptions.input in Vite, otherwise production builds will miss files that Blade still references.
• Named entrypoints in config. Keep a small map in config/vite.php (e.g. 'app' => 'resources/js/app.ts') so Blade templates reference stable names instead of long paths. This also gives you one place to change a path when you split or move bundles.
• Conditional dev-only markup. Use the package's hot-state check (e.g. Vite::isRunningHot()) to render dev-only banners, debug toolbars, or React refresh scripts, and to avoid loading them in production.
• Versioned asset URLs. Use the facade's asset helper (e.g. Vite::asset('resources/images/logo.png')) for files that Vite rewrites, instead of asset(); it resolves through the manifest and keeps cache-busting consistent with your JS/CSS.
• Docker / Sail setups. Run the dev server bound to 0.0.0.0 and set server.hmr.host in vite.config.js to the host the browser can reach. The hot file contains a URL the browser must be able to hit — not just the container.
• Parallel dev workflow. Since this package does not start Vite for you, wire npm run dev and php artisan serve together (e.g. Composer scripts, concurrently, or a Makefile target). Document it so new contributors don't end up with a stale hot file.
• CI/CD. Add npm ci && npm run build before php artisan config:cache and the deploy. Never ship public/hot; delete it on deploy if your pipeline copies the working tree.
• Testing. Feature tests that render Blade will fail if the manifest is missing or the hot file points at a dead server. Either build assets in CI or point the package at an empty/temp manifest in the test environment and assert on the rendered output rather than real files.
• Migration path. For new projects, prefer the first-party laravel-vite-plugin plus Laravel's built-in @vite. To migrate: swap the npm plugin, delete config/vite.php, move the entrypoint list into vite.config.js (laravel({ input: [...], refresh: true })), replace any Vite:: calls with the framework equivalents where they exist, and keep the same @vite([...]) syntax in Blade.

Gotchas and Tips

• Archived means frozen. No fixes for newer Vite major versions, PHP 8.3+, or Laravel changes. Treat it as a legacy dependency and budget time to migrate rather than patching around incompatibilities.
• Stale public/hot is the #1 failure mode. If the dev server crashes or you stop it without cleanup, the file remains and every asset URL points at a dead port. Symptom: blank page with connection-refused errors in the console. Fix: delete public/hot and restart npm run dev.
• "Unable to locate file in Vite manifest" almost always means a path mismatch: the path in Blade (or the named entrypoint in config) doesn't match the key the plugin wrote to manifest.json. Inspect public/build/manifest.json directly — keys are relative source paths, not URLs.
• Manifest path drift. If you change build.outDir in Vite, update build_directory/manifest in config/vite.php to match. They are not derived from each other.
• Config caching. Config is static, so php artisan config:cache is safe, but any environment-specific overrides (e.g. dev server URL) must live in env vars read by the config, not in runtime checks.
• CSP and HMR. In dev, the directive injects module scripts and a WebSocket connection to the Vite server. Strict Content-Security-Policy headers will block these; relax script-src/connect-src for your dev host only.
• Directive name collisions. If you also have the framework's first-party Vite integration or laravel-mix helpers, only one @vite can be registered. Loading both causes confusing "directive not found" or duplicate-injection behavior.
• Windows path separators. Manifest keys use forward slashes; if you build on Windows and reference entrypoints with backslashes in config, lookups can fail. Always use forward-slash relative paths.
• Extension points. For custom behavior (asset URL rewriting, CDN prefixes, per-environment manifests), subclass or rebind the package's Vite service in a service provider rather than editing vendor files; the facade delegates to whatever is bound in the container.
• Debug checklist, in order: (1) does public/hot exist and is Vite running? (2) does public/build/manifest.json exist and contain your entrypoint key? (3) do the config paths and Vite outDir agree? (4) can the browser reach the dev server URL? Ninety percent of issues are one of these four.