start of ai-based development

2026-07-06 10:44:32 +02:00
parent 6573ec6ac1
commit e50099a0c7
10 changed files with 1203 additions and 26 deletions
@@ -0,0 +1,136 @@
+---
+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 + FluentUI + 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**: FluentUI include molti componenti
+- **Fix possibili**:
+  - Tree shaking (import specifici: `import { TextField } from '@fluentui/react'`)
+  - Considerare `@fluentui/react-components` (v9) per bundle più piccoli
+  - 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`