---
name: elixforms-dev-workflow
description: >
  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/`):

```powershell
# 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
```json
"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:

```json
// 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, @fluentui/react
├── package.json
└── scelta-carriera/         ← npm install qui per devDependencies
    ├── node_modules/        ← vite, eslint, plugin, sass-embedded
    └── package.json
```

> **Nota**: Le dipendenze runtime (React, FluentUI) 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).