Com fer servir Laravel Vite amb Bootstrap i Sass

Aquesta setmana, Laravel ha anunciat la migració dels seus projectes de Webpack a Vite.

Qualsevol nova instal·lació de Laravel o els seus starter packs, comptaran amb aquesta nova configuració però també han publicat una guia de migració per actualitzar els projectes existents. Tot i això, si el teu projecte fa servir Sass (com en el cas de Bootstrap) per compilar els assets, no en tindràs prou amb la guia oficial.

Encara no existeix una guia oficial de configuració de Bootstrap amb Vite però hi estan treballant i ja es pot consultar provisionalment.

Si ajuntem les dues guies de migració ens queda un procés igual de senzill.

Migrar de Laravel Mix a Vite amb Bootstrap i Sass

Primer, cal instal·lar Vite i el plugin de Laravel Vite fent servir el teu gestor de paquets npm:

npm install --save-dev vite laravel-vite-plugin

Com que el projecte actual ja està fent servir Bootstrap i Sass, ja hauríeu de tenir les seves dependències però si no és el cas també les heu d'instal·lar:

npm install --save-dev sass bootstrap @popperjs/core

Configurar Vite

Crea el fitxer vite.config.js a l'arrel del teu projecte:

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: {
            '~bootstrap': path.resolve(__dirname, 'node_modules/bootstrap'),
        }
    },
})

Segurament abans estaves indicant el teu fitxer CSS directament al Laravel Mix. Com has vist en el bloc anterior, ara només apuntem el fitxer Javascript. Això és perquè importarem el CSS des del fitxer Javascript.

Scripts NPM

Actualitza els teus scripts NPM al package.json:

  "scripts": {
-     "dev": "npm run development",
-     "development": "mix",
-     "watch": "mix watch",
-     "watch-poll": "mix watch -- --watch-options-poll=1000",
-     "hot": "mix watch --hot",
-     "prod": "npm run production",
-     "production": "mix --production"
+     "dev": "vite",
+     "build": "vite build"
  }

Imports amb ES modules

Vite només és compatible amb ES modules, així que hauràs de canviar qualsevol require() per un import. Pots veure aquesta pull request de Laravel com a exemple.

Carrega Bootstrap

1. Importa el CSS de Bootstrap en els teus estils Sass. Normalment això serà a resources/css/app.scss o resources/sass/app.scss:

// Import all of Bootstrap's CSS
@import "~bootstrap/scss/bootstrap";

2. Carrega el CSS i el Javascript de Bootstrap. Modifica el teu fitxer resources/js/app.js o resources/js/bootstrap.js:

- const bootstrap = require('bootstrap')
- window.bootstrap = bootstrap
+ // Import our custom CSS
+ import '../sass/app.scss'
+ 
+ // Import all of Bootstrap's JS
+ import * as bootstrap from 'bootstrap'

Canvia mix() per @vite

Cal que facis servir la directiva Blade @vite en comptes del helper mix().

- <link rel="stylesheet" href="{{ mix('css/app.css') }}">
- <script src="{{ mix('js/app.js') }}" defer></script>
+ @vite(['resources/js/app.js'])

Recorda que ara no cal fer referència al fitxer CSS perquè es carrega directament amb el Javascript.

Eliminar Laravel Mix

Finalment, només queda eliminar Laravel Mix i les dependències de Webpack que tinguessim instal·lades:

npm remove laravel-mix resolve-url-loader sass-loader
rm webpack.mix.js

En funció del teu procés de deploy, pots afegir al teu .gitignore la ruta on Vite desarà els assets compilats. Per això, afegeix aquest directori:

/public/build