elixforms-web-pages/.agents/skills/create-new-page/SKILL.md

name, description

name	description
elixforms-create-new-page	Guida step-by-step per creare una nuova pagina custom nel progetto elixForms. Copre la struttura dei file, la configurazione Vite per single-bundle, il setup TypeScript, l'importazione dei componenti common, e le convenzioni. Attiva questa skill quando devi creare una nuova pagina, duplicare una pagina esistente, o scaffoldare un nuovo micro-progetto nel monorepo.

Creare una Nuova Pagina elixForms Custom

Prerequisiti

• Node.js installato
• Dipendenze root installate: cd react && npm install

Step 1: Scaffolding con Vite

cd react
npm create vite@latest <nome-pagina> -- --template react
cd <nome-pagina>
npm install vite-plugin-css-injected-by-js
npm install -D sass-embedded

Step 2: Configurare package.json

{
  "name": "@elixforms/<nome-pagina>",
  "private": true,
  "version": "0.0.1",
  "type": "module",
  "scripts": {
    "dev": "vite",
    "build": "vite build",
    "lint": "eslint .",
    "preview": "vite preview"
  },
  "dependencies": {
    "vite-plugin-css-injected-by-js": "^5.0.1"
  },
  "devDependencies": {
    "@vitejs/plugin-react": "^6.0.1",
    "sass-embedded": "^1.99.0",
    "vite": "^8.0.10"
  }
}

Nota: React e ReactDOM NON vanno nel package.json della pagina. Sono nel react/package.json root e vengono risolti via hoisting di npm.

Step 3: Configurare vite.config.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',          // o main.tsx se TypeScript
      output: {
        codeSplitting: false,
        manualChunks: undefined,
        entryFileNames: '<nome-pagina>.js',
        assetFileNames: '[name].[ext]'
      },
    },
    sourcemap: true,
  },
  resolve: {
    alias: {
      "@common": path.resolve(__dirname, "../common"),
    }
  },
  server: {
    fs: {
      allow: [".."]
    }
  }
})

Step 4: Configurare tsconfig.json

{
    "extends": "../tsconfig.base.json",
    "references": [
        { "path": "../common" }
    ],
    "compilerOptions": {
        "rootDir": "src",
        "outDir": "dist",
        "allowJs": true,
        "checkJs": true
    },
    "include": ["src/**/*"]
}

Step 5: Creare il file di dichiarazioni globali

src/global.d.ts:

declare module "*.css";
declare module "*.svg";
declare module "*.png";

Step 6: Creare l'entry point

src/main.jsx (o main.tsx):

import { StrictMode } from 'react'
import { createRoot } from 'react-dom/client'
import './index.css'
import App from './App.jsx'

const rootElement = document.getElementById('root')
if (!rootElement) throw new Error('Root element not found')

createRoot(rootElement).render(
  <StrictMode>
    <App />
  </StrictMode>,
)

Step 7: Creare il componente App

src/App.jsx (o App.tsx):

import './App.css'
import * as ElixForms from '@common/src/ElixFormsComponent';

function App() {
  var myElixFormsReact = new ElixForms.ElixFormsReact({
    description: "Descrizione pagina",
    isDarkTheme: false,
    environmentMessage: "",
    hasTeamsContext: false,
    userDisplayName: "",
    customFormFieldsConfiguration: (formFieldFactory) => (
      <>
        {/* Aggiungi i tuoi campi qui usando formFieldFactory */}
      </>
    )
  });

  var elixFormsReactRender = myElixFormsReact.render();

  return <>
    <div className="container_12" id="pageBody">
      <div className="grid_12">
        <div id="userConsole" className="fe-behaviour">
          {/* Header, contenuto e footer della pagina */}
          <div className="grid_12 console_main">
            <div className="inside">
              <div className="mainview">
                <div className="container">
                  <h1>Titolo Pagina</h1>
                  {elixFormsReactRender}
                </div>
              </div>
            </div>
          </div>
        </div>
      </div>
    </div>
  </>;
}

export default App

Step 8: Configurare i CSS

src/App.css — Importa i CSS remoti del design system elixForms:

@import url('https://console-unipr.elixforms.it/elixFormsCustom/css/elixForms.css');
@import url('https://console-unipr.elixforms.it/rwe2/css/design-bs/bootstrap_adaptation.css');
@import url('https://console-unipr.elixforms.it/rwe2/css/design-bs/console_user.css');
@import url('https://console-unipr.elixforms.it/rwe2/css/design-bs/designitalia_adaptation.css');
@import url('https://console-unipr.elixforms.it/rwe2/css/design-bs/fonts.css');
@import url('https://console-unipr.elixforms.it/rwe2/css/design-bs/style-bs.css');
@import url('https://console-unipr.elixforms.it/rwe2/css/design-bs/style.css');
/* ... altri CSS necessari */

Step 9: Configurare VS Code (opzionale)

Aggiungere configurazione di launch e task in .vscode/launch.json e .vscode/tasks.json seguendo il pattern esistente per scelta-carriera.

Step 10: Build e Deploy

npm run build

Output in dist/:

• <nome-pagina>.js — Singolo bundle JS pronto per il deploy
• Eventuali asset (immagini) referenziati

Checklist Nuova Pagina

• Cartella creata in react/<nome-pagina>/
• package.json con "name": "@elixforms/<nome-pagina>"
• vite.config.js con entryFileNames: '<nome-pagina>.js'
• tsconfig.json estende ../tsconfig.base.json
• Alias @common configurato in vite.config.js
• CSS remoti importati in App.css
• Entry point main.jsx con mount su #root
• global.d.ts con dichiarazioni per moduli CSS/SVG/PNG
• npm install eseguito nella cartella della pagina
• npm run dev funziona senza errori
• npm run build produce singolo bundle in dist/