DOCSEARCHbyAlgolia
Submit Docs

Laravel Vite Documentation

website·Indexed 33 days ago

https://laravel-vite.innocenzi.dev/

A project designed to integrate Vite seamlessly with the Laravel framework. This documentation covers installation, configuration of the Vite plugin and Laravel package, asset management, entrypoints, Blade directives like @vite, and support for Inertia and SSR.

Tokens
8.2K
Snippets
42
Records
75
Agent score
56%

What's inside Laravel Vite

  1. Overview of Laravel Vite integration

    Laravel Vite is designed to integrate Vite into Laravel applications as a replacement for Laravel Mix. The integration consists of three primary components: a PHP package for manifest parsing, Blade directives, and helper functions; a Vite plugin that leverages Laravel's configuration for SSR and multi-config support; and a preset for one-command installation in fresh Laravel projects.

  2. Distinguish between Vite and Laravel Vite configuration

    When using Laravel Vite, configuration is split into two distinct areas:

    1. Vite Configuration: Handled in vite.config.ts. This is used for defining Vite and Rollup plugins. Note that some server and build options are managed by the vite-plugin-laravel plugin and should be handled with care when overriding to avoid breaking functionality.
    2. Laravel Vite Package Configuration: Handled in config/vite.php. This is used for setting up aliases, defining commands that execute before Vite starts, and other package-specific settings.

  3. Implement Server-Side Rendering (SSR) with Laravel Vite

    Laravel Vite supports SSR (currently experimental). Because Vite does not provide a built-in SSR server, you must implement your own using a Node.js framework such as Fastify or Express. Instead of using the standard vite dev command, you start your own server (e.g., via node resources/ssr/server.js).

  4. Manage entrypoints in Laravel Vite

    Entrypoints are the scripts or CSS files that Laravel Vite recognizes and processes, serving as the equivalent to the first parameters in Laravel Mix's .js or .postCss configurations. Entrypoints are configured in config/vite.php and are automatically injected into views via the @vite directive.

  5. Understand Laravel Vite Server and Manifest modes

    Laravel Vite operates in two primary modes to resolve asset tags:

    1. Server mode: Used typically in development. Laravel Vite performs a 'heartbeat check' to see if the development server is running. If it is, assets are served directly from the dev server.
    2. Manifest mode: Used in production or when the dev server is unavailable. Laravel Vite uses the manifest file and the previously generated build to serve assets, ensuring the application remains accessible even without a running dev server.

  6. Run Vite development server using Laravel Sail

    To use Vite with Laravel Sail, you must forward the Vite port (default 5173) in your docker-compose.yml file and configure Vite to listen to 0.0.0.0. Use sail npm ci to install dependencies and sail run dev to start the server.
    # docker-compose.yml
ports:
    - '${APP_PORT:-80}:80'
    - '5173:5173'
    sail npm ci
sail run dev

  7. Meet system requirements for Laravel Vite

    To use Laravel Vite, ensure your environment meets the following minimum requirements:

    • PHP: Version 8.0 or greater (for the Laravel package).
    • Node.js: Version 16.15.1 or greater (for the Vite plugin).
    • Browser Support: Native ESM dynamic import support is required during development. Production builds assume native ESM support via script tags. For legacy browser support, use the official @vitejs/plugin-legacy plugin.

  8. Use a JSON configuration file instead of calling PHP

    To avoid calling the PHP binary during the Vite process, you can extract the configuration to a JSON file. Use the php artisan vite:config command to generate the JSON string. You can then tell Vite to use this file via the CONFIG_PATH_VITE environment variable or the config plugin option. Vite checks CONFIG_PATH_VITE first, then the config option, before falling back to calling the PHP binary.
    # Generate the JSON configuration
php artisan vite:config > vite-config.json

# Tell Vite to use the JSON file via environment variable
CONFIG_PATH_VITE=./vite-config.json

  9. Reference assets in templates and CSS

    Vite statically detects assets referenced in templates or CSS files. You can use absolute, relative, or aliased paths (such as the @ alias) in src attributes or CSS url() functions. These assets are automatically bundled and versioned via the manifest file.
    <img src="@/resources/images/logo.png" alt="My logo" />

  11. Build the SSR server script

    To build the server script for SSR, use the --ssr flag with the Vite build command. The Laravel Vite plugin will use the entrypoint specified in the entrypoints.ssr configuration option (e.g., resources/scripts/ssr.ts). Note that code within the SSR entrypoint must not access the DOM, as it is executed in a Node.js environment.
    vite build --ssr

  12. Start the Vite development server in Laravel

    To start the Vite development server for serving assets (scripts and stylesheets), run the npm run dev command. Note that this server only serves assets; you must still run your application server separately using tools like php artisan serve, Valet, Laragon, or Docker.
    npm run dev