137 lines
3.7 KiB
Markdown
137 lines
3.7 KiB
Markdown
---
|
|
name: elixforms-vite-build-config
|
|
description: >
|
|
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
|
|
|
|
```js
|
|
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
|
|
|
|
```powershell
|
|
# 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`
|