Using Vite

Zap integrates Vite through Zap\Core\Utils\Assets::vite(). Pass Vite entrypoint paths from your controller as the vite view value. The shared layouts.base layout sends the resulting script and stylesheet tags to the browser.

The project includes Vite and the dev and build npm scripts. Install the JavaScript dependencies from the project root:

npm install

The starter Vite configuration uses resources/js/app.js and resources/css/app.css as its entrypoints.

Register entrypoints

Add the entrypoint paths to the data passed to the view. These names must match the paths configured in vite.config.js and, for production, the keys in Vite's manifest.

$data = [
 'vite' => [
 'resources/css/app.css',
 'resources/js/app.js',
 ],
 // Other view data...
];

$html = $this->render('pages/home', $data);

Use vite as the view-data key: the base layout reads that value and calls the asset service. You can supply one entrypoint or an array. CSS entrypoints are emitted as stylesheet links; other entrypoints are emitted as JavaScript modules. CSS imported by a JavaScript entrypoint is also included in production.

Alternatively, call the global vite() helper directly in a Blade view when you need to place the tags yourself. It returns an HTML string, so render it unescaped:

{!! vite(['resources/css/app.css', 'resources/js/app.js']) !!}

Use either the shared layout integration or the direct helper for the same entrypoints, not both, to avoid loading the assets twice.

Development

Set ENVIRONMENT=development in .env, then run the PHP application and Vite in separate terminals:

npm run dev

In development the asset service bypasses the manifest and points entries to http://localhost:5173. It injects Vite's /@vite/client once per page and serves each entrypoint from the dev server. Vite is configured on port 5173 with strict port checking and automatic browser reload when PHP view files change.

Ensure the browser can reach localhost:5173. The DEV_SERVER setting controls how built files are addressed; it does not change the development server URL.

Production build

Build the frontend before deploying:

npm run build

Vite writes the compiled files and manifest under public/build. In production, Zap reads public/build/.vite/manifest.json (or public/build/manifest.json if the first path is absent) and maps each requested entrypoint to its built files.

Set ENVIRONMENT=production for production requests. The browser URL prefix depends on DEV_SERVER: NATIVE uses /build/; other values, including the default WAMP/XAMPP setup, use /public/build/. The manifest remains on disk under public/build in either case.

Troubleshooting

• Development assets fail to load: confirm npm run dev is running and the browser can access localhost:5173.
• Production reports a missing manifest: run npm run build and ensure public/build is deployed.
• An entrypoint is missing: check that its path exactly matches an input in vite.config.js. Unknown manifest keys are skipped.
• Built URLs return 404: check DEV_SERVER against the web-server setup and the public URL prefix it serves.