elixforms-web-pages/.agents/skills/vite-build-config/SKILL.md

name, description

name	description
elixforms-vite-build-config	Configurazione Vite e Rollup per il progetto elixForms. Copre la build single-bundle, i plugin utilizzati, gli alias, il sourcemap, e la strategia CSS (injection nel JS). Attiva questa skill quando devi modificare la build configuration, risolvere problemi di bundling, aggiungere plugin Vite, o ottimizzare l'output di produzione.

Configurazione Vite e Build

Stack di Build

• Vite v8.x — Dev server e bundler
• @vitejs/plugin-react v6.x — Supporto React/JSX
• vite-plugin-css-injected-by-js v5.x — Inietta CSS nel bundle JS
• sass-embedded v1.99.x — Compilazione SCSS (per common/)
• Rollup — Bundler interno di Vite (configurato via rollupOptions)

Configurazione Vite Completa di Riferimento

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import cssInjectedByJsPlugin from 'vite-plugin-css-injected-by-js';
import path from "path";

export default defineConfig({
  plugins: [
    react(),
    cssInjectedByJsPlugin()
  ],
  build: {
    outDir: 'dist',
    cssCodeSplit: false,
    rollupOptions: {
      input: 'src/main.jsx',
      output: {
        codeSplitting: false,
        manualChunks: undefined,
        entryFileNames: '<nome-pagina>.js',
        assetFileNames: '[name].[ext]'
      },
    },
    sourcemap: true,
  },
  resolve: {
    alias: {
      "@common": path.resolve(__dirname, "../common"),
    }
  },
  server: {
    fs: {
      allow: [".."]
    }
  }
})

Dettaglio Opzioni Critiche

Single Bundle (Rollup)

Opzione	Valore	Scopo
codeSplitting	false	Disabilita il code splitting
manualChunks	undefined	Impedisce separazione vendor/app
entryFileNames	'<nome>.js'	Nome deterministico senza hash
assetFileNames	'[name].[ext]'	Asset senza hash nei nomi

CSS Strategy

Opzione	Valore	Scopo
cssCodeSplit	false	No file CSS separati
cssInjectedByJsPlugin()	plugin	CSS iniettato runtime nel DOM via JS

Alias di Import

Alias	Path	Scopo
@common	../common	Accesso alla libreria condivisa

Dev Server

Opzione	Valore	Scopo
server.fs.allow	[".."]	Permette import fuori dalla root del progetto

Comandi

# Dev con HMR
npm run dev

# Build produzione
npm run build

# Preview build produzione
npm run preview

# Lint
npm run lint

Output della Build

dist/
  <nome-pagina>.js      ← Bundle unico (React + CSS + codice)
  <nome-pagina>.js.map  ← Source map
  *.png, *.svg           ← Asset referenziati nel codice

Risoluzione Problemi Comuni

Errore: "The request url is outside of Vite serving allow list"

• Causa: Import di file dalla cartella common/ o altre cartelle esterne
• Fix: Aggiungere server.fs.allow: [".."] nella configurazione Vite

Errore: "Cannot find module '@common/...'"

• Causa: Alias non configurato o path errato
• Fix: Verificare resolve.alias e che la cartella common/ esista

Bundle troppo grande

• Causa: l'uso di componenti UI pesanti o CSS non ottimizzati
• Fix possibili:
  • Mantenere i CSS locali limitati e affidarsi ai CSS remoti del design system
  • Evitare dipendenze UI pesanti per le pagine custom
  • Esternalizzare React se la pagina host lo fornisce già

CSS non applicato in produzione

• Causa: cssInjectedByJsPlugin non installato o non configurato
• Fix: Verificare plugin in vite.config.js e npm install vite-plugin-css-injected-by-js

SCSS non compilato

• Causa: sass-embedded mancante
• Fix: npm install -D sass-embedded