Asset-Bundling mit Vite - Knowledge of Laravel

Was sind Laravel und Vite

Vite ist ein schnelles Frontend-Build-Tool. Während der Entwicklung sorgt Hot Module Replacement (HMR) dafür, dass Änderungen sofort im Browser sichtbar werden; für Produktionsbuilds werden optimierte Assets erzeugt. Seit Laravel 9 ist Vite das Standard-Frontend-Build-Tool und wird über laravel-vite-plugin in Laravel integriert. Das Plugin übernimmt insbesondere folgende Aufgaben:

Verwaltung der Entry Points
HMR-Unterstützung im Entwicklungsserver
Integration in die Blade-Direktive @vite()
Versionierung der Assets im Produktionsbuild (Cache-Busting)

Wenn Sie eines der Starter Kits (etwa Laravel Breeze) verwenden, sind Vite- und Tailwind-Konfiguration bereits enthalten. Auf dieser Seite wird die Einrichtung von Grund auf erläutert.

Eine Einordnung, wie Vite ins Frontend-Setup von Laravel passt, finden Sie zuerst im Überblick unter Frontend.

Installation und Einrichtung

Node prüfen

Für Vite benötigen Sie Node.js (Version 16 oder höher) und npm. Prüfen Sie, ob sie installiert sind:

node -v
npm -v

Pakete installieren

Ein frisch installiertes Laravel-Projekt enthält in der package.json bereits vite und laravel-vite-plugin. Installieren Sie die Abhängigkeiten mit:

npm install

`vite.config.js` konfigurieren

Im Projekt-Root ist bereits eine vite.config.js vorhanden. Geben Sie darin die Entry Points an – also die Dateien, von denen aus die Bundles erstellt werden:

import { defineConfig } from 'vite';
import laravel from 'laravel-vite-plugin';

export default defineConfig({
    plugins: [
        laravel([
            'resources/css/app.css',
            'resources/js/app.js',
        ]),
    ],
});

Bei einer SPA oder mit Inertia wird empfohlen, das CSS aus dem JavaScript zu importieren. Entfernen Sie in diesem Fall resources/css/app.css aus den Entry Points und fügen Sie am Anfang von resources/js/app.js import '../css/app.css'; hinzu.

Entwicklungsserver starten

Starten Sie während der Entwicklung den Vite-Entwicklungsserver mit npm run dev. Bei Dateiänderungen aktualisiert sich der Browser automatisch (HMR).

npm run dev

Sie können ihn auch parallel zum Laravel-Entwicklungsserver starten:

composer run dev

composer run dev startet php artisan serve und npm run dev gleichzeitig.

Blade-Views automatisch neu laden

Mit refresh: true wird der Browser bei Änderungen an Blade-Views oder Routen-Dateien automatisch neu geladen.

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,
        }),
    ],
});

Ist refresh: true gesetzt, werden Änderungen in folgenden Verzeichnissen überwacht:

resources/views/**
app/Livewire/**
routes/**
lang/**

Produktions-Build

Führen Sie vor dem Deploy npm run build aus. Die Assets werden gebündelt, versioniert und nach public/build/ ausgegeben.

npm run build

Beispielhafte Verzeichnisstruktur nach dem Build:

public/
  build/
    assets/
      app-Cv82Mlke.css
      app-DnAZBF4U.js
    manifest.json

Die manifest.json enthält die Zuordnung von Dateinamen zu Hashes. Die Direktive @vite() liest diese Datei aus und lädt so die korrekten Dateien.

Da public/build/ ein Build-Artefakt ist, sollten Sie das Verzeichnis in .gitignore aufnehmen. Führen Sie den Build entweder auf dem Zielsystem oder in CI aus und deployen Sie anschließend.

Assets aus Blade laden

Fügen Sie die Blade-Direktive @vite() im <head> Ihres Layouts ein:

<!DOCTYPE html>
<html lang="de">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>{{ config('app.name') }}</title>

    @vite(['resources/css/app.css', 'resources/js/app.js'])
</head>
<body>
    @yield('content')
</body>
</html>

Wenn Sie CSS im JavaScript importieren, geben Sie nur den JavaScript-Entry-Point an:

@vite('resources/js/app.js')

Die Direktive @vite() wechselt automatisch zwischen Entwicklungs- und Produktionsverhalten:

Situation	Verhalten
Entwicklungsserver läuft	Assets werden vom Vite-Dev-Server geladen, HMR aktiv
Produktion (gebaut)	Es wird `public/build/manifest.json` gelesen und die versionierten Dateien geladen

Entry Points für JavaScript und CSS

JavaScript

resources/js/app.js ist der zentrale Entry Point. Von dort aus importieren Sie weitere Module.

import './bootstrap';
import '../css/app.css';

// Eigene Module importieren
import './components/modal';
import './utils/format';

CSS

Globale Stile schreiben Sie in resources/css/app.css.

/* Bei Verwendung von Tailwind CSS */
@import 'tailwindcss';

/* Eigene Stile */
body {
    font-family: 'Noto Sans JP', sans-serif;
}

Mehrere Entry Points

Wenn Sie für unterschiedliche Bereiche – etwa ein Backend – separate Assets bündeln möchten, geben Sie mehrere Entry Points an:

import { defineConfig } from 'vite';
import laravel from 'laravel-vite-plugin';

export default defineConfig({
    plugins: [
        laravel([
            'resources/css/app.css',
            'resources/js/app.js',
            'resources/css/admin.css',
            'resources/js/admin.js',
        ]),
    ],
});

In Blade laden Sie dann nur die jeweils passenden Entry Points:

{{-- Admin-Layout --}}
@vite(['resources/css/admin.css', 'resources/js/admin.js'])

Integration mit Tailwind CSS

Ab Tailwind CSS v4 wird Tailwind als Vite-Plugin eingebunden.

Tailwind installieren

npm install tailwindcss @tailwindcss/vite

Plugin in vite.config.js einfügen

import { defineConfig } from 'vite';
import laravel from 'laravel-vite-plugin';
import tailwindcss from '@tailwindcss/vite';

export default defineConfig({
    plugins: [
        tailwindcss(),
        laravel([
            'resources/css/app.css',
            'resources/js/app.js',
        ]),
    ],
});

Tailwind im CSS importieren

/* resources/css/app.css */
@import 'tailwindcss';

Wenn Sie Tailwind CSS v3 verwenden, benötigen Sie zusätzlich tailwind.config.js und postcss.config.js. Bei Tailwind CSS v4 sind diese Dateien nicht mehr nötig.

Alias-Konfiguration

laravel-vite-plugin richtet automatisch den Alias @ ein, der auf das Verzeichnis resources/js verweist.

// Import über den Alias
import UserCard from '@/components/UserCard.vue';
// entspricht:
import UserCard from '/resources/js/components/UserCard.vue';

Möchten Sie eigene Aliase ergänzen, setzen Sie sie unter resolve.alias:

import { defineConfig } from 'vite';
import laravel from 'laravel-vite-plugin';
import path from 'path';

export default defineConfig({
    plugins: [
        laravel(['resources/js/app.js']),
    ],
    resolve: {
        alias: {
            '@': '/resources/js',
            '@css': '/resources/css',
            '@images': '/resources/images',
        },
    },
});

Beispiel für Imports mit Aliasen:

import logo from '@images/logo.png';
import '@css/custom.css';

Framework-spezifische Einstellungen

Vue

npm install --save-dev @vitejs/plugin-vue

import { defineConfig } from 'vite';
import laravel from 'laravel-vite-plugin';
import vue from '@vitejs/plugin-vue';

export default defineConfig({
    plugins: [
        laravel(['resources/js/app.js']),
        vue({
            template: {
                transformAssetUrls: {
                    base: null,
                    includeAbsolute: false,
                },
            },
        }),
    ],
});

React

npm install --save-dev @vitejs/plugin-react

import { defineConfig } from 'vite';
import laravel from 'laravel-vite-plugin';
import react from '@vitejs/plugin-react';

export default defineConfig({
    plugins: [
        laravel(['resources/js/app.jsx']),
        react(),
    ],
});

Bei React fügen Sie im Blade-Template die Direktive @viteReactRefresh vor @vite ein:

@viteReactRefresh
@vite('resources/js/app.jsx')

Statische Assets verarbeiten

Auch aus Blade-Templates referenzierte Bilder und Fonts können mit Vite versioniert werden. Legen Sie die betroffenen Verzeichnisse in der Option assets fest:

laravel({
    input: 'resources/js/app.js',
    assets: ['resources/images/**', 'resources/fonts/**'],
})

Im Blade-Template ermitteln Sie die versionierte URL über Vite::asset():

<img src="{{ Vite::asset('resources/images/logo.png') }}" alt="Logo">

Zusammenfassung

Ziel	Vorgehen
Entwicklungsserver starten	`npm run dev`
Produktions-Assets bauen	`npm run build`
Assets in Blade laden	`@vite(['resources/css/app.css', 'resources/js/app.js'])`
Blade-Änderungen automatisch neu laden	`refresh: true` in `vite.config.js` setzen
Tailwind CSS verwenden	Plugin `@tailwindcss/vite` hinzufügen
Alias `@` verwenden	Zeigt standardmäßig auf `resources/js`
Statische Assets versionieren	Option `assets` und `Vite::asset()` nutzen

Nächste Schritte

Cache

Erfahren Sie, wie Sie mit den Cache-Funktionen von Laravel die Performance Ihrer Anwendung weiter steigern.

​Was sind Laravel und Vite

​Installation und Einrichtung

​Node prüfen

​Pakete installieren

​vite.config.js konfigurieren

​Entwicklungsserver starten

​Blade-Views automatisch neu laden

​Produktions-Build

​Assets aus Blade laden

​Entry Points für JavaScript und CSS

​JavaScript

​CSS

​Mehrere Entry Points

​Integration mit Tailwind CSS

​Alias-Konfiguration

​Framework-spezifische Einstellungen

​Vue

​React

​Statische Assets verarbeiten

​Zusammenfassung

​Nächste Schritte

Cache

Was sind Laravel und Vite

Installation und Einrichtung

Node prüfen

Pakete installieren

`vite.config.js` konfigurieren

Entwicklungsserver starten

Blade-Views automatisch neu laden

Produktions-Build

Assets aus Blade laden

Entry Points für JavaScript und CSS

JavaScript

CSS

Mehrere Entry Points

Integration mit Tailwind CSS

Alias-Konfiguration

Framework-spezifische Einstellungen

Vue

React

Statische Assets verarbeiten

Zusammenfassung

Nächste Schritte