elixforms-web-pages/.agents/skills/dev-workflow/SKILL.md

name, description

name	description
elixforms-dev-workflow	Workflow di sviluppo, debug e deploy del progetto elixForms Custom Pages. Copre i comandi per avviare il dev server, buildare, debuggare con VS Code, e le configurazioni di launch/tasks. Attiva questa skill quando devi eseguire comandi di sviluppo, configurare il debug, o gestire il ciclo dev/build/deploy.

Workflow di Sviluppo

Comandi Principali

Tutti i comandi vanno eseguiti dalla cartella della pagina (es. react/scelta-carriera/):

# Installare le dipendenze (prima volta o dopo modifiche a package.json)
cd react
npm install
cd scelta-carriera
npm install

# Avviare il dev server con HMR
npm run dev

# Build per produzione (singolo bundle JS)
npm run build

# Preview della build di produzione
npm run preview

# Lint del codice
npm run lint

Configurazione VS Code

Launch Configurations (.vscode/launch.json)

1. "Scelta Carriere (BROWSER)" — Dev + Chrome Debug

• Avvia npm run dev nella cartella della pagina
• Apre automaticamente Chrome quando il server è pronto
• Pattern di rilevamento: Local:\s+http://localhost:([0-9]+)/
• WebRoot per sourcemaps: ${workspaceFolder}/react/scelta-carriera/src

2. "Scelta Carriere (DEBUG ONLY)" — Solo Dev Server

• Avvia npm run dev senza aprire il browser
• Utile per debug da terminale o browser già aperto

Variabili d'Ambiente

• NO_COLOR: "1" — Disabilita colori ANSI nell'output (migliora leggibilità nel debug console)

Skip Files nel Debug

"skipFiles": [
    "<node_internals>/**",
    "**/node_modules/**",
    "**/@vite/client/**"
]

Tasks (.vscode/tasks.json)

"Start scelta-carriera (Vite App)"

• Task background che avvia npm run dev
• Problem matcher configurato per output Vite:
  • beginsPattern: "VITE"
  • endsPattern: "ready in"

Aggiungere una Nuova Pagina al Debug

Per aggiungere una nuova configurazione di debug per una pagina:

// In .vscode/launch.json, aggiungere in "configurations":
{
  "name": "<Nome Pagina> (BROWSER)",
  "cwd": "${workspaceFolder}/react/<nome-pagina>",
  "env": { "NO_COLOR": "1" },
  "outputCapture": "console",
  "type": "node",
  "request": "launch",
  "runtimeExecutable": "npm",
  "runtimeArgs": ["run", "dev"],
  "skipFiles": [
    "<node_internals>/**",
    "**/node_modules/**",
    "**/@vite/client/**"
  ],
  "serverReadyAction": {
    "action": "debugWithChrome",
    "pattern": "Local:\\s+http://localhost:([0-9]+)/",
    "uriFormat": "http://localhost:%s",
    "webRoot": "${workspaceFolder}/react/<nome-pagina>/src"
  }
}

Flusso di Deploy

1. npm run build nella cartella della pagina
2. Output: dist/<nome-pagina>.js (+ sourcemap e asset)
3. Caricare il file JS sul server remoto console-unipr.elixforms.it
4. La pagina viene servita dalla piattaforma elixForms con i parametri query appropriati

Testing Locale con Query Parameters

Per testare localmente con i parametri elixForms, aggiungere query params all'URL del dev server:

http://localhost:5173/?RWE2_MODULE_ID=123&RWE2_REQUEST_ID=456&COL0002=test&COL0015=3

I valori verranno letti da QueryParamHelper e pre-popoleranno i campi del form.

Struttura delle Dipendenze

react/                       ← npm install qui per dipendenze condivise
├── node_modules/            ← react, react-dom
├── package.json
└── scelta-carriera/         ← npm install qui per devDependencies
    ├── node_modules/        ← vite, eslint, plugin, sass-embedded
    └── package.json

Nota: Le dipendenze runtime (React, ReactDOM) sono nel package.json root. Le dipendenze di sviluppo (Vite, ESLint) sono nel package.json della pagina. npm risolve le dipendenze risalendo la gerarchia delle cartelle (hoisting).