Laravel Vite Plugin

Laravel Vite Plugin is the official integration layer between Laravel and Vite, replacing Laravel Mix as the framework’s default frontend build tool. It configures Vite’s dev server, hot module replacement, and manifest-based asset versioning so that Blade templates can reference compiled assets via the @vite directive without manual wiring.

Beyond basic asset compilation, the plugin handles SSR entry-point builds, TLS detection for Laravel Herd/Valet local development, Laravel Sail Docker networking, full-page reloads on Blade/route/lang file changes, and automatic self-hosted font optimization with local(), google(), bunny(), and fontsource() providers.

What You Get

• A laravel() Vite config function that sets base path, build output directory, manifest generation, and SSR output directory from a single entry-point config or config object
• Automatic dev-server HMR wiring, including a hot file written to the public directory so Blade’s @vite directive knows when the dev server is running
• Built-in support for Laravel Herd/Valet HTTPS certificates and Laravel Sail’s Docker host/port configuration without extra setup
• Full-page reload triggers on changes to Blade views, routes, language files, and Livewire components via the bundled vite-plugin-full-reload dependency
• A fonts sub-plugin (laravel-vite-plugin/fonts) that self-hosts Google/Bunny/Fontsource fonts locally with automatic fallback-metric generation to reduce layout shift
• An inertia-helpers subpath export with resolvePageComponent() for wiring Inertia.js page resolution into a Vite build
• A clean-orphaned-assets CLI binary that removes stale versioned build artifacts left behind by previous builds

Common Use Cases

• Bootstrapping the default Vite config in any Laravel 10+ application to compile resources/css/app.css and resources/js/app.js
• Enabling SSR builds for Inertia.js applications by supplying an ssr entry point alongside the client entry
• Self-hosting Google Fonts or other web fonts to avoid third-party font requests and improve privacy/performance scores
• Running Laravel behind Sail, Herd, or Valet locally where the dev server needs to detect TLS certificates or bind to a Docker-accessible host
• Triggering full-page browser reloads when editing Blade templates or Livewire components during local development

Under The Hood

Architecture The plugin’s entry point, src/index.ts, exports a default laravel() function that resolves a PluginConfig (input entries, public/build directories, hot file path, SSR options, refresh rules, TLS/font settings) and returns an array of Vite plugins: the core laravel plugin object (with config, configResolved, transform, and configureServer hooks), an asset-glob plugin, the fonts sub-plugin from src/fonts/plugin.ts, and vite-plugin-full-reload instances built from the refresh config. The core plugin’s config hook merges Laravel-specific defaults (base path, manifest output, @ resolve alias, CORS origins for *.test domains) into the user’s Vite config without overriding anything the user explicitly set, and configureServer writes a ‘hot’ file to the public directory on dev-server start so the PHP-side @vite Blade directive can detect and proxy to it.

Tech Stack Written in TypeScript targeting ES2020 with strict mode enabled, built via esbuild into ESM output with vite, vite-plugin-full-reload, picocolors, and fontaine treated as externals/peers so the published bundle stays small. Runtime dependencies are minimal (picocolors for terminal colors, tinyglobby for glob matching, vite-plugin-full-reload), and the package declares a vite@^8.0.0 peer dependency plus an optional fontaine@^0.8.0 peer for font fallback-metric generation. The bin/clean.js CLI script and inertia-helpers subpath are compiled separately via tsc.

Code Quality The project has a dedicated tests/ directory with Vitest covering the core plugin (tests/index.test.ts) and each font provider/cache/manifest/CSS-parsing module individually (nine additional test files plus fixture assets), indicating deliberate unit coverage of the trickier font-optimization logic. Source files use consistent naming, exported TypeScript interfaces for all public config shapes (PluginConfig, RefreshConfig), and JSDoc comments on every configurable option describing defaults and behavior, which keeps the single 700+-line index.ts navigable despite its size.

API Design The public API is a single default export accepting either a string, string array, or config object, which lets simple projects pass just an entry-point path while advanced projects opt into SSR, custom directories, TLS detection, and fonts through the same function. Config resolution favors sensible Laravel-convention defaults (public/, build/, manifest.json) so a new Laravel app’s vite.config.js needs only one line to get working HMR and asset versioning, and the /fonts and /inertia-helpers subpath exports keep optional features tree-shakeable and out of the core bundle.