Bundling de assets con Vite - Knowledge of Laravel

Qué son Laravel y Vite

Vite es una herramienta de build de frontend muy rápida. Durante el desarrollo aplica los cambios de forma instantánea gracias a Hot Module Replacement (HMR) y, para producción, genera assets optimizados. Desde Laravel 9, Vite es la herramienta oficial de build del framework y se integra a través de laravel-vite-plugin. Sus funciones principales son:

Gestión de los entry points.
Soporte HMR con el servidor de desarrollo.
Integración con la directiva Blade @vite().
Versionado de los assets (cache busting) en la build de producción.

Si usas un starter kit de Laravel (por ejemplo Laravel Breeze), la configuración de Vite y Tailwind ya viene incluida. Esta página describe cómo hacerlo desde cero.

Para ver el papel de Vite dentro del stack de frontend de Laravel, revisa primero la visión general en frontend.

Instalación y configuración

Comprobar Node

Necesitas Node.js (16 o superior) y npm.

node -v
npm -v

Instalar dependencias

Un proyecto Laravel nuevo ya trae vite y laravel-vite-plugin en package.json. Instala las dependencias con:

npm install

Configurar `vite.config.js`

En la raíz del proyecto se genera vite.config.js. Indica los entry points (archivos desde los que se construye el bundle).

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

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

Con SPAs o Inertia se recomienda importar el CSS desde el JavaScript. En ese caso, elimina resources/css/app.css de los entry points y añade import '../css/app.css'; al principio de resources/js/app.js.

Servidor de desarrollo

Durante el desarrollo, npm run dev arranca el servidor de Vite. Al modificar archivos el navegador se actualiza automáticamente (HMR).

npm run dev

También puedes arrancarlo junto con el servidor de Laravel.

composer run dev

composer run dev arranca php artisan serve y npm run dev a la vez.

Recarga automática de vistas Blade

Con refresh: true el navegador se recarga automáticamente al guardar cambios en vistas Blade o rutas.

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

Con refresh: true se observan los siguientes directorios:

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

Build de producción

Antes de desplegar, ejecuta npm run build. Los assets se agrupan y se versionan en public/build/.

npm run build

Ejemplo de la estructura resultante:

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

manifest.json mapea nombres de archivo a sus hashes; la directiva @vite() lo consulta para cargar los archivos correctos.

Como public/build/ es un artefacto de build, es recomendable añadirlo a .gitignore. Genera la build en el servidor de despliegue o en CI antes de desplegar.

Cargar assets desde Blade

Añade la directiva @vite() en el <head> de tu layout.

<!DOCTYPE html>
<html lang="es">
<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>

Si importas el CSS desde el JavaScript, basta con indicar el entry point de JS.

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

@vite() cambia automáticamente su comportamiento entre desarrollo y producción.

Situación	Comportamiento
Servidor de desarrollo activo	Carga los assets desde Vite y activa HMR
Producción (build hecha)	Consulta `public/build/manifest.json` y carga los archivos versionados

Entry points de JavaScript y CSS

JavaScript

resources/js/app.js es el entry point principal. Desde ahí importas los demás módulos.

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

// Imports personalizados
import './components/modal';
import './utils/format';

CSS

Escribe los estilos globales en resources/css/app.css.

/* Con Tailwind CSS */
@import 'tailwindcss';

/* Estilos personalizados */
body {
    font-family: 'Noto Sans', sans-serif;
}

Varios entry points

Cuando quieras assets distintos por página (por ejemplo, un panel de administración), declara varios entry points.

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

En Blade carga el entry point que corresponda.

{{-- Layout del panel de administración --}}
@vite(['resources/css/admin.css', 'resources/js/admin.js'])

Integración con Tailwind CSS

A partir de Tailwind CSS v4 se integra como plugin de Vite.

Instalar Tailwind

npm install tailwindcss @tailwindcss/vite

Añadir el plugin a vite.config.js

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

Importar Tailwind en el CSS

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

Con Tailwind CSS v3 necesitas tailwind.config.js y postcss.config.js. En Tailwind CSS v4 esos archivos ya no son necesarios.

Aliases

laravel-vite-plugin configura automáticamente el alias @, que apunta a resources/js.

// Import usando el alias
import UserCard from '@/components/UserCard.vue';
// Equivalente a:
import UserCard from '/resources/js/components/UserCard.vue';

Para añadir aliases personalizados usa 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',
        },
    },
});

Ejemplo de uso:

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

Configuración por framework

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

Con React añade en la plantilla Blade la directiva @viteReactRefresh antes de @vite.

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

Assets estáticos

Vite también puede versionar imágenes y fuentes referenciadas desde Blade. Indica los directorios en la opción assets.

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

En Blade obtén la URL versionada con Vite::asset().

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

Resumen

Objetivo	Cómo hacerlo
Arrancar el servidor de desarrollo	`npm run dev`
Generar la build de producción	`npm run build`
Cargar assets desde Blade	`@vite(['resources/css/app.css', 'resources/js/app.js'])`
Recarga automática al editar vistas	`refresh: true` en `vite.config.js`
Usar Tailwind CSS	Añadir el plugin `@tailwindcss/vite`
Usar el alias `@`	Por defecto apunta a `resources/js`
Versionar assets estáticos	Opción `assets` y `Vite::asset()`

Próximos pasos

Caché

Aprende a mejorar aún más el rendimiento de tu aplicación con el sistema de caché de Laravel.

​Qué son Laravel y Vite

​Instalación y configuración

​Comprobar Node

​Instalar dependencias

​Configurar vite.config.js

​Servidor de desarrollo

​Recarga automática de vistas Blade

​Build de producción

​Cargar assets desde Blade

​Entry points de JavaScript y CSS

​JavaScript

​CSS

​Varios entry points

​Integración con Tailwind CSS

​Aliases

​Configuración por framework

​Vue

​React

​Assets estáticos

​Resumen

​Próximos pasos

Caché

Qué son Laravel y Vite

Instalación y configuración

Comprobar Node

Instalar dependencias

Configurar `vite.config.js`

Servidor de desarrollo

Recarga automática de vistas Blade

Build de producción

Cargar assets desde Blade

Entry points de JavaScript y CSS

JavaScript

CSS

Varios entry points

Integración con Tailwind CSS

Aliases

Configuración por framework

Vue

React

Assets estáticos

Resumen

Próximos pasos