Wanneer je een modern Laravel-project opent, kan het bestand vite.config.js in de root in eerste instantie verwarrend zijn; in dit artikel leg ik precies uit wat het duo Vite Laravel doet, waarom je browser tijdens het ontwikkelen direct wordt bijgewerkt, en waar dat mysterieuze manifest.json-bestand voor dient wanneer je naar productie gaat. Sinds Laravel 9.19 is de standaard build-tool niet langer het op Webpack gebaseerde Laravel Mix, maar Vite. Zodra het mentale model eenmaal klikt, wordt het beheren van je CSS- en JavaScript-assets veel aangenamer.
Wat Vite is en waarom het de standaard van Laravel werd
Vite is een frontend build-tool gemaakt door Evan You, de maker van Vue. Het combineert twee taken in één tool: een zeer snelle dev-server tijdens de ontwikkeling, en een geoptimaliseerde, op Rollup gebaseerde bundler voor productie. Het verschil met oudere tools is dat het in ontwikkelingsmodus je code niet vooraf in één grote bundel verpakt. In plaats daarvan benut het de native ES-modules-ondersteuning van de browser en serveert het bestanden alleen wanneer ze worden opgevraagd. Het resultaat: zelfs als je project groeit, start de dev-server vrijwel direct.
De integratie met Laravel wordt verzorgd door het pakket laravel-vite-plugin. Deze plugin vertelt Vite welke bestanden entry points zijn en communiceert met de @vite-directive die je aan de Blade-kant gebruikt.
Installatie en basisconfiguratie
Vite is voorgeïnstalleerd in een nieuw Laravel-project. Twee commando's volstaan om de dependencies te installeren en de dev-server te starten:
npm install
npm run devHet bestand vite.config.js in de projectroot definieert de entry points:
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,
}),
],
});Hier geeft de input-array de hoofdbestanden aan die Vite zal volgen. De optie refresh: true herlaadt de browser automatisch telkens wanneer je Blade-templates, route-bestanden of andere PHP-bronnen opslaat. Aan de Blade-kant voeg je je assets zo toe:
<!DOCTYPE html>
<html>
<head>
@vite(['resources/css/app.css', 'resources/js/app.js'])
</head>De @vite-directive is het magische deel: het past zijn gedrag aan op basis van de omgeving. In ontwikkeling wijst het naar de Vite-server, en in productie naar de gecompileerde bestanden.
HMR in ontwikkeling: waarom de browser direct wordt bijgewerkt
HMR (Hot Module Replacement) is het mechanisme dat, wanneer je een bestand opslaat, alleen de gewijzigde module in de browser injecteert zonder de hele pagina te herladen. Wanneer npm run dev draait, opent Vite standaard een dev-server op poort 5173. Tegelijkertijd wordt er een klein bestand met de naam public/hot in de projectroot aangemaakt; daarin staat het adres van de dev-server.
Elke keer dat een pagina wordt gerenderd, controleert de @vite-directive eerst of dit public/hot-bestand bestaat. Als dat zo is, serveert het de assets niet zelf; in plaats daarvan richt het de tags op de Vite-server en wordt er een WebSocket-verbinding opgezet. Wanneer je een CSS-bestand wijzigt, worden de stijlen bijgewerkt zonder dat de pagina überhaupt herlaadt; wanneer je één JavaScript-module bewerkt, verandert alleen die module. Dit versnelt de ontwikkelflow enorm omdat het de applicatiestatus (formulierinvoer, geopende modals) behoudt.
- Geen volledige herlaad: alleen de gewijzigde module wordt bijgewerkt en de paginastatus blijft behouden.
- Directe feedback: je ziet de wijziging op het moment dat je opslaat.
- Automatische injectie: nieuwe
import-dependencies die je toevoegt worden direct opgelost.
Bundling en de manifest-logica in productie
Wanneer je klaar bent om live te gaan, voer je npm run build uit. In deze fase gebruikt Vite Rollup om alle modules te combineren, dode code te verwijderen (tree-shaking), de JavaScript en CSS te minificeren, en een op inhoud gebaseerde hash aan de bestandsnamen toe te voegen. De output wordt naar de map public/build geschreven.
Die hash is cruciaal: in plaats van app.js krijg je een naam als app-4ed1f8c2.js. Telkens wanneer de inhoud van het bestand verandert, verandert ook de hash. Dit lost fundamenteel het probleem op dat de browser en het CDN een oude versie uit de cache serveren (cache busting). Maar je kunt die willekeurige hash niet met de hand in je Blade-template schrijven. Hier komt het manifest in beeld.
Aan het einde van de build genereert Vite public/build/.vite/manifest.json. Dit bestand koppelt bronbestandsnamen aan gecompileerde outputs. Een vereenvoudigd voorbeeld ziet er zo uit:
{
"resources/js/app.js": {
"file": "assets/app-4ed1f8c2.js",
"isEntry": true,
"css": ["assets/app-1b2c3d4e.css"]
}
}In een productieomgeving kan de @vite(['resources/js/app.js'])-directive het public/hot-bestand niet vinden, dus leest hij het manifest. Vanuit het bronpad vindt hij de echte gehashte bestandsnaam en genereert hij de juiste <script>- en <link>-tags. Jij schrijft het bronpad, en Laravel lost via het manifest het juiste fysieke bestand op. Daarom moet de map public/build altijd naar de server worden gedeployd.
Veelvoorkomende problemen en hun oplossingen
De meest voorkomende fout bij een Vite Laravel-setup is de melding "Unable to locate file in Vite manifest" in productie. Dit wordt vrijwel altijd veroorzaakt doordat npm run build niet is uitgevoerd, of doordat de map public/build ontbreekt op de server. Een paar praktische punten:
- Bouw bij het deployen: voer altijd
npm run builduit voordat je live gaat en stuur de mappublic/buildmee. - Commit het
public/hot-bestand niet: als het nanpm run devblijft staan, blijft productie ten onrechte de dev-server zoeken. Sluit dev netjes af metCtrl+C. Vite::asset()voor statische assets: om naar bestanden zoals afbeeldingen te verwijzen, plaats je ze onderresources/en gebruik je de helper, of gebruik je de public-map rechtstreeks.- Achter SSL/proxy: als de HMR-verbinding niet tot stand komt in Docker of een externe dev-omgeving, moet je mogelijk de
server.hmr-instellingen invite.config.jsaanpassen aan je host.
Veelgestelde vragen
Wat is het verschil tussen Vite en Laravel Mix?
Laravel Mix was een wrapper bovenop Webpack en was traag in ontwikkeling omdat het de hele bundel vanaf nul opnieuw compileerde. Vite gebruikt native ES-modules in ontwikkeling en start dus direct, en optimaliseert met Rollup in productie. Sinds Laravel 9.19 is Vite de standaard voor nieuwe projecten; Mix wordt nog steeds ondersteund, maar Vite wordt aanbevolen voor nieuw werk.
Moet ik de map public/build aan Git toevoegen?
Meestal niet. Deze map is de gecompileerde output en wordt doorgaans aan .gitignore toegevoegd; in plaats daarvan draait npm run build tijdens de deploy-stap. Als je echter op shared hosting zit waar je de build-stap niet kunt uitvoeren, is het committen van de map en deze direct meesturen ook een geldige strategie.
Moeten npm run dev en php artisan serve tegelijk draaien in ontwikkeling?
Ja. php artisan serve (of je webserver) serveert de PHP-applicatie, terwijl npm run dev de Vite-server in een aparte terminal opent en HMR levert. Als beide samen draaien, halen Blade-pagina's hun assets van de Vite-server.
Wordt je frontend build-proces traag of krijg je Vite-manifest-fouten? Ik kan je helpen met het opzetten van de asset pipeline, deploy-automatisering en performance in Laravel-projecten. Neem contact op en laten we het over je project hebben.