Wenn du ein modernes Laravel-Projekt öffnest, kann die Datei vite.config.js im Stammverzeichnis zunächst verwirrend wirken; in diesem Artikel erkläre ich genau, was das Duo Vite Laravel macht, warum sich dein Browser während der Entwicklung sofort aktualisiert und wozu diese geheimnisvolle manifest.json-Datei dient, wenn du in Produktion gehst. Seit Laravel 9.19 ist das Standard-Build-Tool nicht mehr das auf Webpack basierende Laravel Mix, sondern Vite. Sobald das mentale Modell einmal sitzt, wird die Verwaltung deiner CSS- und JavaScript-Assets deutlich angenehmer.
Was Vite ist und warum es zum Standard von Laravel wurde
Vite ist ein Frontend-Build-Tool, das von Evan You, dem Schöpfer von Vue, entwickelt wurde. Es vereint zwei Aufgaben in einem Werkzeug: einen sehr schnellen Dev-Server während der Entwicklung und einen optimierten, auf Rollup basierenden Bundler für die Produktion. Der Unterschied zu älteren Tools besteht darin, dass es deinen Code im Entwicklungsmodus nicht vorab zu einem großen Bundle zusammenpackt. Stattdessen nutzt es die native ES-Modul-Unterstützung des Browsers und liefert Dateien nur dann aus, wenn sie angefordert werden. Das Ergebnis: Selbst wenn dein Projekt wächst, startet der Dev-Server nahezu sofort.
Die Integration mit Laravel übernimmt das Paket laravel-vite-plugin. Dieses Plugin teilt Vite mit, welche Dateien Einstiegspunkte (Entry Points) sind, und kommuniziert mit der @vite-Direktive, die du auf der Blade-Seite verwendest.
Installation und grundlegende Konfiguration
Vite ist in einem neuen Laravel-Projekt vorinstalliert. Zwei Befehle genügen, um die Abhängigkeiten zu installieren und den Dev-Server zu starten:
npm install
npm run devDie Datei vite.config.js im Projektstamm definiert die Einstiegspunkte:
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 gibt das input-Array die Hauptdateien an, die Vite verfolgen wird. Die Option refresh: true lädt den Browser automatisch neu, sobald du Blade-Templates, Route-Dateien oder andere PHP-Quellen speicherst. Auf der Blade-Seite bindest du deine Assets so ein:
<!DOCTYPE html>
<html>
<head>
@vite(['resources/css/app.css', 'resources/js/app.js'])
</head>Die @vite-Direktive ist der magische Teil: Sie ändert ihr Verhalten je nach Umgebung. In der Entwicklung verweist sie auf den Vite-Server, in der Produktion auf die kompilierten Dateien.
HMR in der Entwicklung: warum der Browser sich sofort aktualisiert
HMR (Hot Module Replacement) ist der Mechanismus, der beim Speichern einer Datei nur das geänderte Modul in den Browser injiziert, ohne die ganze Seite neu zu laden. Wenn npm run dev läuft, öffnet Vite standardmäßig einen Dev-Server auf Port 5173. Gleichzeitig wird im Projektstamm eine kleine Datei namens public/hot angelegt, die die Adresse des Dev-Servers enthält.
Jedes Mal, wenn eine Seite gerendert wird, prüft die @vite-Direktive zuerst, ob diese public/hot-Datei existiert. Wenn ja, liefert sie die Assets nicht selbst aus; stattdessen richtet sie die Tags auf den Vite-Server und es wird eine WebSocket-Verbindung aufgebaut. Wenn du eine CSS-Datei änderst, werden die Stile aktualisiert, ohne dass die Seite überhaupt neu lädt; wenn du ein einzelnes JavaScript-Modul bearbeitest, ändert sich nur dieses Modul. Das beschleunigt den Entwicklungsfluss enorm, weil der Anwendungszustand (Formulareingaben, geöffnete Modals) erhalten bleibt.
- Kein vollständiges Neuladen: Nur das geänderte Modul wird aktualisiert, und der Seitenzustand bleibt erhalten.
- Sofortiges Feedback: Du siehst die Änderung in dem Moment, in dem du speicherst.
- Automatische Injektion: Neue
import-Abhängigkeiten, die du hinzufügst, werden sofort aufgelöst.
Bundling und die Manifest-Logik in der Produktion
Wenn du bereit bist, live zu gehen, führst du npm run build aus. In dieser Phase nutzt Vite Rollup, um alle Module zusammenzuführen, toten Code zu entfernen (Tree-Shaking), JavaScript und CSS zu minifizieren und den Dateinamen einen inhaltsbasierten Hash hinzuzufügen. Die Ausgabe wird in den Ordner public/build geschrieben.
Dieser Hash ist entscheidend: Statt app.js erhältst du einen Namen wie app-4ed1f8c2.js. Sobald sich der Inhalt der Datei ändert, ändert sich auch der Hash. Damit wird das Problem grundlegend gelöst, dass Browser und CDN eine alte Version aus dem Cache ausliefern (Cache-Busting). Aber du kannst diesen zufälligen Hash nicht von Hand in dein Blade-Template schreiben. Genau hier kommt das Manifest ins Spiel.
Am Ende des Builds erzeugt Vite public/build/.vite/manifest.json. Diese Datei ordnet Quelldateinamen den kompilierten Ausgaben zu. Ein vereinfachtes Beispiel sieht so aus:
{
"resources/js/app.js": {
"file": "assets/app-4ed1f8c2.js",
"isEntry": true,
"css": ["assets/app-1b2c3d4e.css"]
}
}In einer Produktionsumgebung findet die @vite(['resources/js/app.js'])-Direktive die public/hot-Datei nicht, also liest sie das Manifest. Aus dem Quellpfad findet sie den echten gehashten Dateinamen und erzeugt die korrekten <script>- und <link>-Tags. Du schreibst den Quellpfad, und Laravel löst über das Manifest die richtige physische Datei auf. Deshalb muss der Ordner public/build immer auf den Server deployt werden.
Häufige Probleme und ihre Lösungen
Der häufigste Fehler bei einem Vite-Laravel-Setup ist die Meldung „Unable to locate file in Vite manifest" in der Produktion. Das liegt fast immer daran, dass npm run build nicht ausgeführt wurde oder der Ordner public/build auf dem Server fehlt. Ein paar praktische Hinweise:
- Beim Deployment bauen: Führe vor dem Live-Gang immer
npm run buildaus und übertrage den Ordnerpublic/build. - Die
public/hot-Datei nicht committen: Bleibt sie nachnpm run devbestehen, sucht die Produktion fälschlicherweise weiter nach dem Dev-Server. Beende die Entwicklung sauber mitStrg+C. Vite::asset()für statische Assets: Um auf Dateien wie Bilder zu verweisen, lege sie unterresources/ab und nutze den Helper, oder verwende den Public-Ordner direkt.- Hinter SSL/Proxy: Wenn die HMR-Verbindung in Docker oder einer entfernten Dev-Umgebung nicht zustande kommt, musst du eventuell die
server.hmr-Einstellungen invite.config.jsan deinen Host anpassen.
Häufig gestellte Fragen
Was ist der Unterschied zwischen Vite und Laravel Mix?
Laravel Mix war ein Wrapper auf Basis von Webpack und war in der Entwicklung langsam, weil es das gesamte Bundle von Grund auf neu kompilierte. Vite nutzt in der Entwicklung native ES-Module und startet daher sofort, und optimiert in der Produktion mit Rollup. Seit Laravel 9.19 ist Vite der Standard für neue Projekte; Mix wird weiterhin unterstützt, aber für neue Arbeiten wird Vite empfohlen.
Sollte ich den Ordner public/build zu Git hinzufügen?
In der Regel nicht. Dieser Ordner ist die kompilierte Ausgabe und wird üblicherweise zur .gitignore hinzugefügt; stattdessen läuft npm run build im Deploy-Schritt. Wenn du jedoch auf Shared Hosting bist, wo du den Build-Schritt nicht ausführen kannst, ist es auch eine valide Strategie, den Ordner zu committen und direkt zu übertragen.
Sollten npm run dev und php artisan serve in der Entwicklung gleichzeitig laufen?
Ja. php artisan serve (oder dein Webserver) liefert die PHP-Anwendung aus, während npm run dev den Vite-Server in einem separaten Terminal öffnet und HMR bereitstellt. Wenn beide zusammen laufen, beziehen Blade-Seiten ihre Assets vom Vite-Server.
Wird dein Frontend-Build-Prozess langsam oder bekommst du Vite-Manifest-Fehler? Ich kann dir bei der Einrichtung der Asset-Pipeline, der Deploy-Automatisierung und der Performance in Laravel-Projekten helfen. Nimm Kontakt auf, und lass uns über dein Projekt sprechen.