Vite

Per que Vite?#

Qualsevol aplicacio web moderna necessita un sistema que agafi els fitxers font de CSS i JavaScript, els processi i els prepari per al navegador. Aquesta eina s'anomena bundler. Un bundler s'encarrega de tasques com ara transformar codi TypeScript a JavaScript estàndard, compilar Sass a CSS, minificar fitxers per reduir-ne la mida, afegir prefixos de compatibilitat entre navegadors i generar noms de fitxer amb hash per invalidar la cache del navegador quan el contingut canvia. Sense un bundler, hauries de gestionar manualment les dependencies entre fitxers, preocupar-te per la compatibilitat i servir fitxers sense optimitzar.

Durant anys, Laravel va utilitzar Laravel Mix com a eina de bundling. Laravel Mix era un wrapper elegant per sobre de webpack que simplificava la seva configuracio. Tot i que webpack es una eina molt potent, te un problema fonamental: es lent. Cada vegada que fas un canvi a un fitxer, webpack ha de reconstruir tot el bundle, cosa que en projectes grans pot trigar diversos segons. A mes, la configuracio de webpack es complexa i sovint requereix ajustaments manuals per a casos d'us comuns.

A partir de Laravel 9.19, el framework va adoptar Vite com a bundler per defecte. Vite representa un canvi de paradigma en el desenvolupament frontend. En mode de desenvolupament, Vite serveix els fitxers directament al navegador utilitzant moduls ES natius, cosa que fa que l'inici del servidor sigui pràcticament instantani independentment de la mida del projecte. Quan modifiques un fitxer, Vite aplica els canvis al navegador en mil·lisegons gracies al Hot Module Replacement (HMR) sense necessitat de recarregar la pagina. Per a la compilacio de produccio, Vite utilitza Rollup, un bundler optimitzat que genera fitxers petits i eficients amb tree-shaking, code splitting i minificacio automatica.

El paquet laravel-vite-plugin es el pont entre Vite i Laravel. Aquest plugin s'encarrega de connectar el servidor de desenvolupament de Vite amb les plantilles Blade de Laravel, gestionar la generacio del manifest de fitxers compilats i configurar automaticament les rutes dels assets. Gracies a aquest plugin, la integracio es transparent: nomes cal definir els punts d'entrada i Vite s'encarrega de la resta.

Configuracio#

Quan crees un projecte Laravel nou, trobaras un fitxer vite.config.js a l'arrel del projecte. Aquest fitxer es el cor de la configuracio de Vite i defineix com es processaran els teus assets. La funcio defineConfig proporciona autocompletat a l'editor i valida l'estructura de la configuracio. El plugin de Laravel s'importa del paquet laravel-vite-plugin i s'afegeix a la llista de plugins de Vite.

L'opcio input es un array que defineix els punts d'entrada de la teva aplicacio. Cada punt d'entrada es un fitxer que Vite processara com a arrel d'un arbre de dependencies. Si el teu fitxer app.js importa altres moduls, Vite els seguira i els inclourà automaticament al bundle. Es important entendre que nomes has de llistar els fitxers d'entrada, no tots els fitxers del projecte. L'opcio refresh indica a Vite que ha de recarregar la pagina automaticament quan detecti canvis als fitxers Blade o de rutes, ja que aquests canvis no es poden aplicar amb HMR.

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

Si la teva aplicacio te seccions diferenciades, com ara una area publica i un panell d'administracio, pots definir multiples punts d'entrada. Cadascun generara el seu propi bundle independent amb nomes les dependencies necessaries. Aixo evita que l'usuari que visita la pagina publica hagi de descarregar el JavaScript del panell d'administracio i viceversa.

import { defineConfig } from 'vite';
import laravel from 'laravel-vite-plugin';
 
export default defineConfig({
    plugins: [
        laravel({
            input: [
                'resources/css/app.css',
                'resources/js/app.js',
                'resources/css/admin.css',
                'resources/js/admin.js',
            ],
            refresh: true,
        }),
    ],
});

L'opcio refresh accepta mes configuracio que un simple booleà. Pots especificar exactament quins directoris o patrons de fitxer han de provocar una recàrrega. Aixo es util si tens fitxers Blade en ubicacions personalitzades o si vols que la recàrrega s'activi quan modifiques fitxers de rutes:

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: [
                'resources/views/**',
                'routes/**',
                'app/Livewire/**',
            ],
        }),
    ],
});

Incloure assets a Blade#

Un cop tens Vite configurat, has de dir a les teves plantilles Blade on incloure els fitxers CSS i JavaScript compilats. Laravel proporciona la directiva @vite per a aquesta tasca. Aquesta directiva es intel·ligent: sap si estàs en mode de desenvolupament o de produccio i genera les etiquetes HTML adequades per a cada cas. Nomes cal que passis el mateix array de fitxers que has definit com a punts d'entrada a la configuracio de Vite.

<!DOCTYPE html>
<html lang="ca">
<head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <title>La meva aplicacio</title>
    @vite(['resources/css/app.css', 'resources/js/app.js'])
</head>
<body>
    {{ $slot }}
</body>
</html>

La diferencia entre el mode de desenvolupament i el de produccio es clau per entendre com funciona @vite. Quan el servidor de desenvolupament de Vite esta en marxa, la directiva genera etiquetes que apunten directament al servidor de Vite (normalment a http://localhost:5173). Aixo permet que el HMR funcioni, ja que el navegador es connecta directament amb Vite per rebre les actualitzacions en temps real. Quan compiles per a produccio, la directiva genera etiquetes normals amb les rutes als fitxers compilats i versionats dins de public/build/.

En mode de desenvolupament, @vite genera etiquetes com aquestes:

<script type="module" src="http://localhost:5173/@vite/client"></script>
<link rel="stylesheet" href="http://localhost:5173/resources/css/app.css">
<script type="module" src="http://localhost:5173/resources/js/app.js"></script>

En produccio, les etiquetes apunten als fitxers compilats amb hash:

<link rel="stylesheet" href="/build/assets/app-4f8g7h2j.css">
<script type="module" src="/build/assets/app-9k3m5n1p.js"></script>

El fitxer public/build/manifest.json es el que fa possible aquesta transformacio. Quan executes npm run build, Vite genera aquest fitxer manifest que mapeja cada fitxer font al seu fitxer compilat corresponent. Laravel llegeix aquest manifest per generar les URLs correctes a les etiquetes HTML. No has d'editar mai aquest fitxer manualment; es genera automaticament amb cada compilacio.

{
    "resources/css/app.css": {
        "file": "assets/app-4f8g7h2j.css",
        "src": "resources/css/app.css"
    },
    "resources/js/app.js": {
        "file": "assets/app-9k3m5n1p.js",
        "src": "resources/js/app.js",
        "isEntry": true
    }
}

Si la teva aplicacio te layouts diferents per a seccions diferents, pots fer servir @vite amb assets especifics a cada layout. Per exemple, el layout principal podria incloure els assets publics, mentre que el layout d'administracio inclou els seus propis:

{{-- resources/views/layouts/admin.blade.php --}}
<!DOCTYPE html>
<html lang="ca">
<head>
    @vite(['resources/css/admin.css', 'resources/js/admin.js'])
</head>
<body>
    <div class="admin-panel">
        {{ $slot }}
    </div>
</body>
</html>

Servidor de desenvolupament#

Per iniciar el servidor de desenvolupament de Vite, nomes cal executar la comanda npm run dev. Aquesta comanda arrenca un servidor local (per defecte al port 5173) que serveix els teus assets de forma directa. El servidor es comunica amb el navegador a traves d'un WebSocket per enviar actualitzacions en temps real quan modifiques un fitxer. Es important tenir tant el servidor de Laravel (php artisan serve o un entorn amb Valet/Herd) com el servidor de Vite funcionant alhora.

# En un terminal, arrenca el servidor de Laravel
php artisan serve
 
# En un altre terminal, arrenca Vite
npm run dev

El Hot Module Replacement (HMR) es una de les funcionalitats mes potents de Vite i una de les raons principals per les quals va substituir Laravel Mix. Amb HMR, quan modifiques un fitxer, Vite detecta el canvi i envia nomes la part modificada al navegador. El navegador aplica el canvi sense recarregar tota la pagina. Aixo significa que l'estat de la teva aplicacio es manté: els formularis no perden les dades introduides, els modals no es tanquen i les animacions no es reinicien. El resultat es un cicle de desenvolupament molt mes fluid i rapid.

El comportament del HMR varia segons el tipus de fitxer. Amb fitxers CSS, el canvi s'aplica instantàniament: modifiques un color, guardes el fitxer i el navegador mostra el nou color immediatament sense cap recàrrega. Amb fitxers JavaScript, el comportament depen del framework que facis servir. Vue.js i React tenen suport natiu per a HMR a nivell de component, cosa que significa que pots modificar un component i veure'n el resultat al navegador sense perdre l'estat dels altres components. Per a JavaScript pla, Vite recarregarà la pagina completament quan detecti un canvi.

Hi ha alguns problemes habituals que pots trobar amb el servidor de desenvolupament. Si fas servir HTTPS al teu entorn local, hauràs de configurar Vite per a que tambe serveixi amb HTTPS. Si treballes amb Docker o Laravel Sail, el servidor de Vite s'executa dins del contenidor i potser no es accessible directament des del teu navegador. En aquests casos, cal ajustar la configuracio del servidor:

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,
        }),
    ],
    server: {
        host: '0.0.0.0',
        hmr: {
            host: 'localhost',
        },
    },
});

Si fas servir Laravel Sail, la configuracio requereix especificar el host del HMR perque el WebSocket pugui connectar-se correctament des del navegador al contenidor Docker:

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,
        }),
    ],
    server: {
        host: '0.0.0.0',
        port: 5173,
        strictPort: true,
        hmr: {
            host: 'localhost',
            port: 5173,
        },
    },
});

Treballar amb CSS#

Vite processa els fitxers CSS de forma nativa i ofereix suport integrat per a PostCSS, la qual cosa fa que configurar Tailwind CSS sigui senzill. PostCSS es un processador de CSS que transforma el teu codi CSS mitjancant plugins. Tailwind CSS funciona com un plugin de PostCSS que genera classes d'utilitat a partir de les directives que defineixis al teu fitxer CSS. Per configurar Tailwind, necessites tres coses: instal·lar els paquets, crear el fitxer de configuracio de Tailwind i definir les directives al teu fitxer CSS principal.

npm install -D tailwindcss postcss autoprefixer
npx tailwindcss init -p

El fitxer postcss.config.js que genera l'ultima comanda defineix els plugins de PostCSS que Vite aplicara als teus fitxers CSS. Tailwind s'encarrega de generar les classes d'utilitat i autoprefixer afegeix automaticament els prefixos de navegador necessaris (-webkit-, -moz-, etc.) perque el teu CSS funcioni a tots els navegadors moderns.

// postcss.config.js
export default {
    plugins: {
        tailwindcss: {},
        autoprefixer: {},
    },
};

Al fitxer tailwind.config.js, has d'indicar a Tailwind on buscar les classes CSS per generar nomes les que realment fas servir. El camp content es un array de patrons de fitxer que Tailwind analitzara:

// tailwind.config.js
/** @type {import('tailwindcss').Config} */
export default {
    content: [
        './resources/**/*.blade.php',
        './resources/**/*.js',
        './resources/**/*.vue',
    ],
    theme: {
        extend: {},
    },
    plugins: [],
};

Amb la configuracio en lloc, el teu fitxer CSS principal fa servir les directives de Tailwind per incloure els estils base, els components i les utilitats. A continuacio, pots afegir els teus estils personalitzats:

/* resources/css/app.css */
@tailwind base;
@tailwind components;
@tailwind utilities;
 
/* Estils personalitzats */
.btn-primary {
    @apply bg-blue-500 text-white px-4 py-2 rounded hover:bg-blue-600;
}
 
.card {
    @apply bg-white shadow-md rounded-lg p-6;
}

Si prefereixes treballar amb Sass en lloc de CSS pur, Vite ofereix suport natiu. Nomes cal instal·lar el compilador de Sass i pots comencar a fer servir fitxers .scss directament als teus punts d'entrada. No cal configurar res mes a vite.config.js, ja que Vite detecta automaticament els fitxers Sass i els processa:

npm install -D sass

Un cop instal·lat, pots crear fitxers Sass i importar-los normalment. Vite processara les variables, els mixins, els nesting i totes les funcionalitats de Sass automaticament:

// resources/css/app.scss
$primary-color: #3b82f6;
$border-radius: 0.5rem;
 
.button {
    background-color: $primary-color;
    border-radius: $border-radius;
    padding: 0.5rem 1rem;
 
    &:hover {
        background-color: darken($primary-color, 10%);
    }
 
    &--large {
        padding: 1rem 2rem;
        font-size: 1.25rem;
    }
}

Si fas servir Sass, recorda actualitzar el punt d'entrada a la configuracio de Vite:

laravel({
    input: ['resources/css/app.scss', 'resources/js/app.js'],
    refresh: true,
}),

Vite tambe processa el CSS de formes avancades en produccio. Automaticament divideix el CSS en fitxers separats (code splitting) si fas servir importacions dinamiques, minifica tot el codi eliminant espais i comentaris innecessaris, i genera noms de fitxer amb hash per a la invalidacio de cache. Aixo significa que quan desplegues una nova versio, els navegadors descarregaran nomes els fitxers que han canviat.

Treballar amb JavaScript#

El punt d'entrada principal de JavaScript es normalment resources/js/app.js. Aquest fitxer es on importes les teves dependencies globals, inicialitzes frameworks i configures la teva aplicacio. Vite processara aquest fitxer i seguira totes les importacions per generar el bundle final. Es bona practica organitzar el codi en moduls separats i importar-los des del punt d'entrada principal per mantenir el codi net i estructurat.

// resources/js/app.js
import './bootstrap';
import Alpine from 'alpinejs';
 
window.Alpine = Alpine;
Alpine.start();

El fitxer bootstrap.js que Laravel inclou per defecte configura algunes dependencies basiques com Axios per a peticions HTTP. Pots personalitzar-lo segons les necessitats del teu projecte o afegir-hi la configuracio de biblioteques addicionals:

// resources/js/bootstrap.js
import axios from 'axios';
 
window.axios = axios;
window.axios.defaults.headers.common['X-Requested-With'] = 'XMLHttpRequest';

Si tens pagines amb necessitats especifiques de JavaScript que no vols carregar a totes les pagines, pots crear punts d'entrada separats. Per exemple, una pagina amb un editor de text enriquit podria tenir el seu propi fitxer JavaScript:

// resources/js/editor.js
import ClassicEditor from '@ckeditor/ckeditor5-build-classic';
 
ClassicEditor
    .create(document.querySelector('#editor'))
    .catch(error => {
        console.error(error);
    });

{{-- Nomes a la vista de l'editor --}}
@vite(['resources/css/app.css', 'resources/js/app.js', 'resources/js/editor.js'])

Vite ofereix suport natiu per a TypeScript. No cal instal·lar res addicional ni configurar cap loader: simplement renomena els teus fitxers de .js a .ts i Vite s'encarregara de la transpilacio. Aixo es un avantatge important respecte a webpack, que necessitava un loader especific (ts-loader o babel-loader amb presets de TypeScript). Vite utilitza esbuild per a la transpilacio de TypeScript, que es ordres de magnitud mes rapid que les alternatives basades en webpack.

// resources/js/app.ts
import './bootstrap';
import { createApp } from 'vue';
import App from './App.vue';
 
interface User {
    id: number;
    name: string;
    email: string;
}
 
const app = createApp(App);
app.mount('#app');

Si el teu projecte utilitza Vue.js, cal afegir el plugin de Vue a la configuracio de Vite. El plugin s'encarrega de processar els fitxers .vue (Single File Components) i d'activar el HMR a nivell de component. La configuracio del template.transformAssetUrls es necessaria perque les URLs dels assets dins dels templates de Vue es processin correctament:

import { defineConfig } from 'vite';
import laravel from 'laravel-vite-plugin';
import vue from '@vitejs/plugin-vue';
 
export default defineConfig({
    plugins: [
        laravel({
            input: ['resources/css/app.css', 'resources/js/app.js'],
            refresh: true,
        }),
        vue({
            template: {
                transformAssetUrls: {
                    base: null,
                    includeAbsolute: false,
                },
            },
        }),
    ],
    resolve: {
        alias: {
            vue: 'vue/dist/vue.esm-bundler.js',
        },
    },
});

De la mateixa manera, si prefereixes React, cal afegir el plugin corresponent. El plugin de React configura automaticament el Fast Refresh, que es l'equivalent del HMR per a components React:

npm install -D @vitejs/plugin-react

import { defineConfig } from 'vite';
import laravel from 'laravel-vite-plugin';
import react from '@vitejs/plugin-react';
 
export default defineConfig({
    plugins: [
        laravel({
            input: ['resources/css/app.css', 'resources/js/app.jsx'],
            refresh: true,
        }),
        react(),
    ],
});

Imatges i assets estatics#

Quan treballes amb imatges i altres fitxers estatics a una aplicacio Laravel amb Vite, es important entendre la diferencia entre fitxers processats i fitxers estatics. Els fitxers dins del directori resources/ son processats per Vite: se'ls aplica hashing, optimitzacio i es mouen al directori de compilacio. Els fitxers dins del directori public/ es serveixen directament sense cap processament. Aquesta distincio determina com has de referenciar els fitxers en cada cas.

Per a imatges que vols que Vite processi (afegint hash per a cache busting, per exemple), col·loca-les dins de resources/images/ i utilitza el helper Vite::asset() a les teves plantilles Blade. Aquest helper consulta el manifest per trobar la ruta correcta del fitxer processat:

{{-- Imatge processada per Vite amb hash al nom --}}
<img src="{{ Vite::asset('resources/images/logo.png') }}" alt="Logo">
 
{{-- Imatge estàtica al directori public (sense processament) --}}
<img src="/images/hero-background.jpg" alt="Hero">

L'avantatge de processar les imatges amb Vite es que cada vegada que modifiques una imatge, el fitxer compilat tindrà un nom diferent (per exemple, logo-a3b5c7d9.png). Aixo forca els navegadors a descarregar la versio nova en lloc de mostrar la versio en cache. Per a imatges que no canvien mai o que son molt grans, es mes pràctic posar-les directament al directori public/ per evitar processar-les amb cada compilacio.

Dins dels fitxers JavaScript, pots importar imatges directament. Vite retornara la URL del fitxer processat que pots fer servir com a src d'una etiqueta d'imatge o com a fons d'un element:

// Importar una imatge retorna la seva URL processada
import logoUrl from '../images/logo.png';
 
const img = document.createElement('img');
img.src = logoUrl;
document.body.appendChild(img);

Al CSS, les referencies a imatges amb rutes relatives tambe es processen automaticament per Vite. Les URLs es resolen i els fitxers es copien al directori de compilacio amb hash:

.hero {
    background-image: url('../images/hero-bg.jpg');
    background-size: cover;
    background-position: center;
}

Àlies de ruta#

A mesura que el teu projecte creix, les importacions relatives es poden tornar difícils de llegir i mantenir. Expressions com import Component from '../../../components/Component' son confuses i fragils: si mous un fitxer, totes les rutes relatives han de canviar. Vite permet definir alies de ruta que substitueixen una part de la ruta per un prefix curt, normalment @/. Aixo fa que les importacions siguin mes clares i independents de l'estructura de directoris.

Per configurar un àlies de ruta, afegeix la propietat resolve.alias a la configuracio de Vite. El modul path de Node.js s'utilitza per generar rutes absolutes:

import { defineConfig } from 'vite';
import laravel from 'laravel-vite-plugin';
import path from 'path';
 
export default defineConfig({
    plugins: [
        laravel({
            input: ['resources/css/app.css', 'resources/js/app.js'],
            refresh: true,
        }),
    ],
    resolve: {
        alias: {
            '@': path.resolve(__dirname, 'resources/js'),
            '@components': path.resolve(__dirname, 'resources/js/components'),
            '@utils': path.resolve(__dirname, 'resources/js/utils'),
        },
    },
});

Amb els alies configurats, les importacions es simplifiquen considerablement. Independentment de on estigui el fitxer que fa la importacio, la ruta es la mateixa:

// Sense àlies (difícil de llegir)
import Button from '../../../components/Button';
import { formatDate } from '../../utils/dates';
 
// Amb àlies (clar i consistent)
import Button from '@components/Button';
import { formatDate } from '@utils/dates';

Si fas servir TypeScript o vols que l'editor reconegui els alies per a l'autocompletat i la navegacio, has de mantenir la configuracio sincronitzada amb el fitxer jsconfig.json o tsconfig.json. Les rutes definides en aquests fitxers han de coincidir amb les de vite.config.js:

{
    "compilerOptions": {
        "baseUrl": ".",
        "paths": {
            "@/*": ["resources/js/*"],
            "@components/*": ["resources/js/components/*"],
            "@utils/*": ["resources/js/utils/*"]
        }
    }
}

Variables d'entorn#

En moltes aplicacions frontend, necessites accedir a variables de configuracio com ara URLs d'APIs externes, claus publiques de serveis o modes de depuracio. Vite proporciona un mecanisme per exposar variables d'entorn al codi del client a traves de l'objecte import.meta.env. Tanmateix, hi ha una restriccio de seguretat important: nomes les variables que comencin amb el prefix VITE_ estaran disponibles al codi del client. Aquesta restriccio existeix perque tot el codi JavaScript del client es visible al navegador, i sense aquest filtre podries exposar accidentalment secrets com claus de base de dades o tokens d'API.

Les variables d'entorn es defineixen al fitxer .env del teu projecte Laravel. Les variables amb el prefix VITE_ estaran disponibles tant al servidor (PHP) com al client (JavaScript). Les variables sense aquest prefix nomes seran accessibles des de PHP:

# .env
APP_NAME="La meva aplicacio"
APP_DEBUG=true
 
# Aquestes variables estaran disponibles al JavaScript del client
VITE_APP_NAME="La meva aplicacio"
VITE_API_URL="https://api.exemple.com"
VITE_PUSHER_APP_KEY="la-teva-clau-publica"
VITE_ANALYTICS_ID="UA-12345678"
 
# Aquestes NO estaran disponibles al client (sense prefix VITE_)
DB_PASSWORD=secret
API_SECRET_KEY=super-secret

Al teu codi JavaScript, pots accedir a les variables amb import.meta.env. Vite reemplaca aquestes referencies pel valor real durant la compilacio, cosa que significa que no hi ha cap peticio addicional al servidor: els valors queden incrustats directament al codi compilat:

// Accedir a variables d'entorn
const apiUrl = import.meta.env.VITE_API_URL;
const appName = import.meta.env.VITE_APP_NAME;
 
// Variables integrades de Vite
console.log(import.meta.env.MODE); // 'development' o 'production'
console.log(import.meta.env.DEV);  // true en desenvolupament
console.log(import.meta.env.PROD); // true en produccio
 
// Exemple pràctic: configurar Axios
import axios from 'axios';
 
const api = axios.create({
    baseURL: import.meta.env.VITE_API_URL,
    headers: {
        'Accept': 'application/json',
    },
});
 
export default api;

Es important recordar que qualsevol variable amb el prefix VITE_ serà visible per a qualsevol persona que inspeccioni el codi font al navegador. Mai posis secrets, contrasenyes o tokens privats en variables amb prefix VITE_. Per a operacions que requereixen credencials privades, fes sempre la peticio des del backend PHP.

Compilar per a produccio#

Quan la teva aplicacio esta llesta per a produccio, has d'executar la comanda de compilacio que generara els fitxers optimitzats. Aquesta comanda executa Rollup per sota, que es l'eina que Vite fa servir per a les compilacions de produccio. Rollup es especialment bo en tree-shaking (eliminar codi que no es fa servir), code splitting (dividir el codi en chunks mes petits) i minificacio (reduir la mida dels fitxers eliminant espais, comentaris i reduint noms de variables).

npm run build

Despres d'executar la comanda, trobaras tots els fitxers compilats dins del directori public/build/. L'estructura tipica te un subdirectori assets/ amb els fitxers CSS, JavaScript i qualsevol altre recurs processat. Cada fitxer te un hash al nom que canvia quan el contingut del fitxer es modifica. Aixo es el que s'anomena cache busting o versionat d'assets:

public/
  build/
    manifest.json
    assets/
      app-4f8g7h2j.css
      app-9k3m5n1p.js
      logo-a3b5c7d9.png

El hash al nom del fitxer es fonamental per al rendiment. Quan desplegues una nova versio, els fitxers que no han canviat mantenen el mateix nom i els navegadors els serveixen des de la cache. Els fitxers que han canviat tenen un nom diferent, cosa que forca el navegador a descarregar la versio nova. Aixo et permet configurar capçaleres de cache molt agressives (per exemple, Cache-Control: max-age=31536000) sense preocupar-te de que els usuaris vegin versions antigues.

El tree-shaking es un proces que Rollup aplica automaticament. Si importes una funcio especifica d'una biblioteca gran, Rollup incloura nomes el codi necessari per a aquella funcio i eliminara la resta. Per exemple, si importes debounce de Lodash, nomes s'incloura el codi de la funcio debounce i les seves dependencies internes, no tota la biblioteca Lodash. Perque el tree-shaking funcioni correctament, es important fer servir importacions amb nom en lloc d'importar el modul sencer:

// Bo: importacio amb nom, permet tree-shaking
import { debounce } from 'lodash-es';
 
// Dolent: importa tot el modul, no permet tree-shaking
import _ from 'lodash';

Quan desplegues la teva aplicacio, nomes necessites pujar el directori public/build/ juntament amb la resta del codi PHP. El directori node_modules/ i els fitxers font de resources/ no son necessaris al servidor de produccio. En la majoria d'entorns de desplegament, el proces de compilacio es fa com a part del pipeline de CI/CD:

# Proces tipic de desplegament
npm ci
npm run build
php artisan migrate --force
php artisan config:cache
php artisan route:cache
php artisan view:cache

Configuracio avancada#

Per a projectes mes complexos, Vite ofereix opcions de configuracio avancades que permeten adaptar el proces de compilacio a necessitats especifiques. Una de les configuracions mes habituals es el Server-Side Rendering (SSR), que permet generar el HTML al servidor per millorar el rendiment inicial de càrrega i l'indexacio per part dels motors de cerca.

El laravel-vite-plugin suporta SSR de forma nativa. Cal definir un punt d'entrada per al servidor (un fitxer JavaScript que exporta una funcio de renderitzat) i indicar-lo a la configuracio:

import { defineConfig } from 'vite';
import laravel from 'laravel-vite-plugin';
import vue from '@vitejs/plugin-vue';
 
export default defineConfig({
    plugins: [
        laravel({
            input: 'resources/js/app.js',
            ssr: 'resources/js/ssr.js',
            refresh: true,
        }),
        vue({
            template: {
                transformAssetUrls: {
                    base: null,
                    includeAbsolute: false,
                },
            },
        }),
    ],
});

El fitxer SSR conté la logica de renderitzat al servidor. En el cas de Vue, utilitza createSSRApp en lloc de createApp i renderToString per generar el HTML:

// resources/js/ssr.js
import { createSSRApp, h } from 'vue';
import { renderToString } from '@vue/server-renderer';
import { createInertiaApp } from '@inertiajs/vue3';
 
export default function render(page) {
    return createInertiaApp({
        page,
        render: renderToString,
        resolve: (name) => {
            const pages = import.meta.glob('./Pages/**/*.vue', { eager: true });
            return pages[`./Pages/${name}.vue`];
        },
        setup({ App, props, plugin }) {
            return createSSRApp({
                render: () => h(App, props),
            }).use(plugin);
        },
    });
}

Per compilar l'aplicacio amb SSR, executa les dues comandes de compilacio:

npm run build
node bootstrap/ssr/ssr.js

Una altra configuracio avancada habitual es la integracio amb Ziggy per poder generar URLs de rutes de Laravel directament des del JavaScript. Ziggy exporta les definicions de rutes de Laravel a un objecte JavaScript que pots fer servir amb el helper route() al frontend. Aixo es especialment util quan fas servir Inertia.js o construeixes SPAs que necessiten referenciar rutes de Laravel:

composer require tightenco/ziggy

// resources/js/app.js
import { route } from 'ziggy-js';
import { Ziggy } from './ziggy';
 
// Ara pots generar URLs de Laravel al JavaScript
const userUrl = route('users.show', { id: 1 }, undefined, Ziggy);
console.log(userUrl); // /usuaris/1

Per generar el fitxer de definicions de rutes que Ziggy necessita:

php artisan ziggy:generate resources/js/ziggy.js

Finalment, Vite permet afegir plugins personalitzats per a tasques especifiques. Per exemple, pots afegir un plugin per comprimir els fitxers de sortida amb gzip o Brotli, o un plugin per generar sprites SVG a partir dels teus icones:

import { defineConfig } from 'vite';
import laravel from 'laravel-vite-plugin';
import compression from 'vite-plugin-compression';
import { createSvgIconsPlugin } from 'vite-plugin-svg-icons';
import path from 'path';
 
export default defineConfig({
    plugins: [
        laravel({
            input: ['resources/css/app.css', 'resources/js/app.js'],
            refresh: true,
        }),
        compression({
            algorithm: 'brotliCompress',
        }),
        createSvgIconsPlugin({
            iconDirs: [path.resolve(process.cwd(), 'resources/icons')],
            symbolId: 'icon-[name]',
        }),
    ],
    build: {
        rollupOptions: {
            output: {
                manualChunks: {
                    vendor: ['vue', 'axios'],
                },
            },
        },
    },
});

La propietat build.rollupOptions.output.manualChunks permet controlar com Vite divideix el codi en fitxers separats. A l'exemple anterior, Vue i Axios es col·loquen en un chunk vendor separat. Aixo es util perque les biblioteques de tercers canvien amb menys frequencia que el teu codi, i els navegadors poden mantenir el chunk de vendor en cache mentre descarreguen nomes el chunk del teu codi quan publiques una actualitzacio.