Regione Toscana Design System - Servizi Vedi Libreria Core

Installazione e sviluppo

Configurazione per la modalità di sviluppo in Njk e Tailwind

Installazione

Clonare il repository, poi eseguire nella cartella del progetto:

npm install

per installare le dipendenze.
È necessaria almeno la versione 20.9.0 di Node.

Sviluppo

Avvio Fractal Core

npm run start

Avvia il server Fractal Core (port 3000) + Webpack watch + CSS watch in parallelo.

Avvio Fractal Servizi

npm run start:servizi

Avvia il server Fractal Servizi (port 3010) + Webpack watch + CSS watch.

Avvio Core + Servizi insieme

npm run start:all

Avvia entrambi i server Fractal (Core port 3000, Servizi port 3010) condividendo un’unica istanza di Webpack watch e CSS watch, utile per verificare i link incrociati tra le due istanze.

Con quattro processi avviati insieme, nei primi secondi il browser può restituire “Page not found”: i server non hanno ancora completato l’avvio. Ricaricare la pagina quando sono pronti.

Build

Build completa (Core + Servizi)

npm run build

Esegue in sequenza: clean → webpack prod → build CSS componenti → build CSS bundle → minify CSS → build Fractal Core → build Fractal Servizi → build portal.

Build Fractal Core

npm run build:fractal

Genera la build statica Fractal Core in dist/core/. Esegue automaticamente sync:changelog prima del build (via prebuild:fractal).

Build Fractal Servizi

node scripts/fractal-servizi-build.js

Genera la build statica Fractal Servizi in dist/servizi/.

Build della sola istanza Servizi

npm run build:servizi

Webpack + CSS componenti + bundle + build statica Fractal Servizi, senza toccare dist/core/ né il portale. Utile per iterare sui soli componenti di 07-widgets/ e 08-servizi/.

Landing page del portale

npm run build:portal

Genera dist/index.html - la pagina che smista verso Core e Servizi - da portal/portale.njk e portal/portale.context.yml, usando l’engine Nunjucks di Fractal. Va eseguito dopo le due build statiche, che devono già esistere quando la pagina le linka. È l’ultimo passo di npm run build.

Build JS e CSS di base (webpack)

npm run build:webpack

Produce public/js/componentsJs.js - il JavaScript di tutti i componenti - più public/css/core.css e public/css/main.css, dalle entry in assets/css/. È il primo passo di npm run build.

Build CSS componenti

npm run build:components           # tutti i componenti
npm run build:components:servizi   # solo 08-servizi/
npm run build:components:widgets   # solo 07-widgets/

Compila i CSS individuali di ogni componente.

Build CSS bundle

npm run build:bundle               # tutti i bundle definiti - oggi solo servizi
npm run build:bundle:servizi       # lo stesso bundle, indicato esplicitamente

scripts/build-bundle-css.js definisce un solo bundle, servizi: aggrega i *.built.css di 07-widgets/ e 08-servizi/ in public/css/servizi.css. I due comandi qui sopra fanno quindi la stessa cosa.

core.css non passa di qui: lo produce webpack, insieme a main.css e a componentsJs.js.

Minifica CSS

npm run minify-css                 # main.css  → main.min.css  (monolite pre-split)
npm run minify-css:core            # core.css  → core.min.css
npm run minify-css:servizi         # servizi.css → servizi.min.css

I tre bundle hanno ciascuno il proprio minificato. main.min.css esiste ancora perché il wrapper di preview di Fractal carica il monolite; il pacchetto di distribuzione spedisce core.min.css e servizi.min.css.

Pacchetto di distribuzione

npm run build:package              # canale staging → dist/rtds-current.zip
npm run build:release              # canale release → dist/rtds-{version}.zip

Un unico assemblatore (scripts/build-package.js) per i due canali: monta il pacchetto in una cartella temporanea di sistema, renderizza i componenti via API Fractal, riscrive i path degli asset in base alla profondità di ogni file, prepara il sottoinsieme cdn/, verifica che ogni riferimento risolva e comprime il risultato in dist/.

La verifica finale interrompe la build se uno snippet referenzia un asset che non esiste nel pacchetto, o se una url() di un CSS assemblato non risolve: è il modo in cui un componente nuovo con un asset dimenticato si fa notare, invece di produrre un archivio rotto in silenzio.

La cartella di lavoro vive nella temp di sistema e sparisce a fine script. Su build fallita resta, e lo script ne stampa il percorso; --keep la conserva anche a build riuscita.

Build staging (Fractal + hub)

npm run build:staging

Esegue npm run build + npm run build:temp + npm run build:package.

Hub di staging (Storybook + indice)

npm run build:temp

Costruisce le due istanze Storybook in dist/temp/core/ e dist/temp/servizi/ e genera l’indice dist/temp/index.html che le collega. Scrive solo sotto dist/temp/: a differenza di build:storybook:core/:servizi, non sovrascrive le build statiche di Fractal.

Pulizia dist

npm run clean

Cancella l’intera cartella dist/.

Storybook (predisposizione iniziale)

Storybook è configurato nel progetto come predisposizione per un futuro workflow di documentazione. Gli script sono disponibili ma non fanno parte del flusso di sviluppo corrente.

Avvio Storybook Core (sviluppo)

npm run storybook:core     # port 6006
npm run storybook:servizi  # port 6007

Build Storybook

npm run build:storybook:core      # output: dist/core/
npm run build:storybook:servizi   # output: dist/servizi/

Attenzione: le due destinazioni sono le stesse delle build statiche di Fractal, che vengono quindi sovrascritte. La build di staging usa infatti build:temp, che scrive in dist/temp/.

Rigenerazione degli asset Storybook

npm run generate-storybook-assets

Rigenera i .stories.js e le cartelle _html/ dei componenti, che non sono versionati. Ogni comando Storybook qui sopra lo invoca già da sé; serve a mano solo per allineare gli asset senza avviare né buildare Storybook.

Sprite SVG

Compila solo lo sprite

npm run build-svg-sprite

Genera public/icons.svg dallo sprite SVG in public/svgs/.

Compila sprite + aggiorna config yml

npm run build-svgs

Compila lo sprite SVG e aggiorna i file .config.yml dei componenti icone.

Release

Rilascio di una versione

npm run release

Avvia release-it: bump della versione, generazione della sezione tecnica del CHANGELOG.md dai conventional commit, commit di rilascio, tag e push. Prima del tag esegue in automatico normalize:changelog e build:release, così la zip versionata è prodotta dallo stesso codice che sta per essere taggato.

Normalizzazione del changelog

npm run normalize:changelog

Fonde nella stessa sezione di versione la parte scritta a mano per chi integra il DS - il blocco [Da rilasciare] - e la parte tecnica generata dai commit. È invocato da npm run release: a mano serve solo per verificare l’esito su una sezione già scritta.

Utility

Sync changelog in Fractal

npm run sync:changelog

Copia CHANGELOG.md dalla root in docs/fondamenta/changelog.md per renderlo navigabile in Fractal. Eseguito automaticamente prima di ogni build:fractal.

ZIP delle immagini

npm run zip-images                # nome: images.zip
npm run zip-images-with-date      # nome: images-YYYYMMDD-HHMMSS.zip

Crea un archivio ZIP della cartella public/images/.

Snippet HTML per Storybook

npm run build-html-snippets

Copia le cartelle components/**/_html/ - generate da migrate-to-stories.js - in dist/html-snippets/.

Nessuna build lo invoca e oggi niente consuma il suo output: il pacchetto di distribuzione renderizza i componenti da sé tramite l’API di Fractal, e Storybook usa le _html/ generate accanto ai sorgenti, non questa copia. dist/html-snippets/ è stata rimossa dal repository. Lo script resta come residuo del meccanismo precedente.