---
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`