Alby96andClaude Opus 5.5 bce6cdabad
CI / Verifica (lint, build, test, Lighthouse, pacchetto) (push) Successful in 6m36s
CI / Link esterni (non bloccante) (push) Successful in 1m55s
fix(vscode): dipendenze installate da sole prima dell'avvio con F5
Nel checkout principale mancava node_modules: le configurazioni di avvio puntano a
node_modules/astro/bin/astro.mjs e fallivano subito. Ora un preLaunchTask («Sito:
dipendenze», scripts/ensure-deps.mjs) esegue npm ci solo se node_modules manca, se manca
una dipendenza diretta o se package-lock.json è più recente dell'ultima installazione;
altrimenti esce subito. Lo stesso controllo precede la build dell'anteprima. README e
CHANGELOG lo descrivono, con il messaggio di Astro quando un server è già avviato.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-15 11:43:16 +01:00

Sito web dello Studio Grasso

Sito statico dello Studio Grasso — Studio Tributario e Societario (Montegrosso d'Asti e Asti), realizzato con Astro. Nessun tracciamento, nessun cookie, nessuna risorsa di terze parti caricata senza un'azione esplicita dell'utente; pacchetto di rilascio universale (un file zip di soli file statici, con .htaccess) pronto per qualsiasi hosting.

Requisiti

  • Node.js LTS: versione in .nvmrc (24), minimo 22.22.3. Con nvm: nvm install && nvm use.
  • npm (incluso in Node.js).
  • Per i test: Chromium di Playwright. Se manca: npx playwright install --with-deps chromium (una volta sola).

Avvio rapido

npm ci            # installa le dipendenze esatte di package-lock.json
npm run dev       # sito in sviluppo su http://localhost:4321 (si aggiorna a ogni modifica)
npm run build     # genera il sito statico in dist/
npm run preview   # serve dist/ su http://127.0.0.1:4321
npm run verify    # tutti i controlli di qualità (gli stessi della CI)
npm run package   # crea lo zip di rilascio in release/

Avvio in debug con VS Code

Aprire la cartella del repository in VS Code, poi il pannello Esegui e debug (Ctrl+Maiusc+D), scegliere una configurazione e premere F5. Prima di ogni avvio il task «Sito: dipendenze» (scripts/ensure-deps.mjs) esegue npm ci se node_modules manca o è più vecchia di package-lock.json, per esempio su un clone appena fatto o dopo un pull che ha cambiato le dipendenze; altrimenti è immediato.

Configurazione Cosa fa
Sito: sviluppo (Edge) / (Chrome) astro dev con il debugger di Node; quando il server è pronto apre il browser con il debugger collegato (punti di interruzione negli script di src/scripts/)
Sito: anteprima della build (Edge) esegue npm run build e serve dist/ come in produzione su http://127.0.0.1:4321

Maiusc+F5 ferma il server e chiude il browser quando è selezionata la sessione del server, come all'avvio. Dopo una pausa su un punto di interruzione nel browser è selezionata la sessione del browser, e Maiusc+F5 chiude solo quella: premerlo una seconda volta, oppure usare Stop sulla sessione «Sito: sviluppo» nel pannello dello stack di chiamate. Le configurazioni sono in .vscode/launch.json e .vscode/tasks.json. Astro avvia un solo server di sviluppo per progetto: se npm run dev è già aperto in un terminale, chiuderlo prima di premere F5 (altrimenti l'avvio si ferma con «Another astro dev server is already running»; npx astro dev stop chiude quello rimasto aperto).

Comandi

Comando Cosa fa
npm run dev server di sviluppo
npm run build build statica in dist/
npm run preview anteprima di dist/
npm run lint ESLint (JavaScript, TypeScript, Astro)
npm run format / format:check Prettier: corregge / verifica la formattazione
npm run check astro check: tipi TypeScript e componenti
npm run test:html validità HTML di tutte le pagine (html-validate)
npm run test:links link interni, asset e ancore (linkinator); -- --external anche i siti esterni
npm run test:e2e test end-to-end (Playwright): pagine, navigazione, menu, privacy, mappa, modulo
npm run test:a11y accessibilità: axe su tutte le pagine a 1440 e 390 px, tastiera, zoom, reflow
npm run test:compliance conformità (P.IVA, pagine legali, nessun tracciamento, JSON-LD, titoli professionali…)
npm run test:lighthouse Lighthouse CI: Performance ≥ 0.95, Accessibility 1, Best Practices ≥ 0.95, SEO 1
npm test html + link + e2e + a11y + conformità
npm run verify lint + formattazione + tipi + build + npm test + Lighthouse
npm run package build + zip in release/ + verifica del contenuto dello zip (test:package)
npm run icons rigenera marchio, favicon, apple-touch-icon e immagine di condivisione

npm run verify deve terminare senza errori prima di ogni rilascio: la CI ne ripete i controlli uno per uno e release.yml lo esegue prima di creare lo zip.

Struttura

src/data/          dati e testi: studio.ts (anagrafica, sedi, orari, professionisti, abilitazioni,
                   partner, modulo), pagine.ts (testi delle pagine), testi.ts, navigazione.ts
src/content/       servizi/*.md, legali/*.md (privacy, cookie, note legali, accessibilità),
                   link-utili.json — schemi in src/content.config.ts
src/components/    componenti Astro (intestazione, footer, card, mappa, modulo…)
src/layouts/       BaseLayout.astro: <head>, SEO, dati strutturati, struttura della pagina
src/pages/         una pagina per file; servizi/[slug].astro genera le 6 pagine dei servizi
src/styles/        tokens.css (colori, tipografia, spaziature), global.css, fonts.css, print.css
src/scripts/       piccoli script: menu, mappa su consenso, modulo, ancore del vecchio sito
public/            .htaccess, favicon e immagini statiche (copiati così come sono)
scripts/           script di test, pacchetto, icone, note di rilascio, upload della release,
                   dipendenze prima dell'avvio da VS Code (ensure-deps.mjs)
tests/             e2e/ e a11y/ (Playwright), helpers/
deploy/            nginx.conf.example, optional-php-form/contact.php, gitea-deploy.yml.example
                   (esempio di deploy automatico, disattivato)
.gitea/workflows/  ci.yml (verifica e zip di prova) e release.yml (zip e pubblicazione della release)
.vscode/           launch.json e tasks.json: avvio del sito in debug (F5)
docs/              brief, mockup, guide di deploy e contenuti, conformità
site.config.mjs    dominio pubblico del sito (unica fonte per build, test e pacchetto)

Configurazione

Impostazione Dove Valore predefinito
Dominio del sito (canonical, sitemap, robots, dati strutturati) site.config.mjs, oppure variabile SITE_URL (in CI: variabile del repository SITE_URL) https://www.grassoezio.it
Modulo di contatto: off, php, endpoint MODALITA_PREDEFINITA in src/data/studio.ts, oppure variabile CONTACT_FORM_MODE off (card «Scrivici una e-mail»)
Data riproducibile (anno nel footer, date negli archivi) variabile SOURCE_DATE_EPOCH ora corrente / data dell'ultimo commit

Le variabili valgono per tutti i comandi della sessione (build, verify, package), non solo per la build. Esempio, nel terminale di VS Code (PowerShell):

$env:SITE_URL = 'https://studiograssoezio.it'
npm run verify
Remove-Item Env:SITE_URL

In Git Bash, macOS o Linux: SITE_URL=https://studiograssoezio.it npm run verify. Per un cambio di dominio definitivo modificare invece il valore in site.config.mjs, oppure la variabile del repository SITE_URL su Gitea (Impostazioni → Actions → Variabili), che CI e release usano per la build. Lo zip della release contiene un sito costruito per quel dominio.

Per verificare il modulo attivo (validazione, anti-spam, pagina di conferma), in PowerShell:

$env:CONTACT_FORM_MODE = 'php'
npm run build
npx playwright test tests/e2e/form.spec.ts
Remove-Item Env:CONTACT_FORM_MODE
npm run build   # ripristina la versione senza modulo

In Git Bash, macOS o Linux: CONTACT_FORM_MODE=php npm run build && npx playwright test tests/e2e/form.spec.ts && npm run build.

Pubblicare il repository su Gitea

Il repository è su Gitea: https://gitea.encke-hake.ts.net/BalboSoft/Studio_Grasso. In un clone il remote origin è già configurato (git remote -v per controllare). Per un repository nuovo: git remote add origin <url-del-repository>.

git push -u origin main          # pubblica il codice: parte la CI (.gitea/workflows/ci.yml)
git push origin vX.Y.Z           # pubblica un tag: parte la release (.gitea/workflows/release.yml)

Consigliato: proteggere il branch main (Impostazioni del repository → Branch → nuova regola per main: niente push forzati, merge solo con i controlli di stato, cioè la CI, superati) e lavorare con branch e pull request. I messaggi di commit seguono Conventional Commits in italiano (feat:, fix:, docs:, ci:, test:, chore:).

CI e release usano Gitea Actions, con i workflow in .gitea/workflows/:

  • ci.yml parte a ogni push su main, a ogni pull request e a mano dalla scheda Actions: ripete passo per passo i controlli di npm run verify (così si vede subito quale è fallito), poi crea lo zip di rilascio e ne verifica il contenuto.
  • release.yml parte a ogni tag vX.Y.Z: verifica tutto, crea lo zip e lo pubblica nella sezione Release (vedi sotto).

I job girano su un runner act_runner con label ubuntu-latest, il label predefinito di act_runner (modificabile in cima ai file dei workflow). Perché i workflow partano, le Actions devono essere attive sul repository (Impostazioni del repository → «Enable Repository Actions») e il runner deve essere registrato su Gitea. I runner del repository, con i loro label, e il token per registrarne uno nuovo si trovano in Impostazioni del repository → Actions → Runner (<url-del-repository>/settings/actions/runners); i passi per l'installazione e la registrazione sono nella guida di Gitea Actions. Le azioni di terze parti (checkout, setup-node, upload-artifact) sono indicate con URL completo su github.com, quindi non dipendono dalla configurazione dell'istanza, ma il runner deve poter raggiungere github.com. I report dei test sono caricati con upload-artifact@v3: la v4 non funziona su Gitea.

Fare una release

  1. Aggiornare version in package.json (SemVer: si aumenta l'ultima cifra per le correzioni, la cifra centrale per le novità, la prima per i cambiamenti importanti) e npm install per allineare package-lock.json.

  2. Aggiungere in CHANGELOG.md la sezione ## [X.Y.Z] - AAAA-MM-GG: diventa il testo della release.

  3. npm run verify, commit (chore(release): prepara vX.Y.Z) e push su main.

  4. Creare e pubblicare il tag:

    git tag vX.Y.Z
    git push origin vX.Y.Z
    

Il workflow release.yml verifica che tag, package.json e CHANGELOG coincidano, esegue npm run verify e npm run package e pubblica nella sezione Release del repository (https://gitea.encke-hake.ts.net/BalboSoft/Studio_Grasso/releases) un solo file allegato: sito-studio-grasso-vX.Y.Z.zip. È il sito pronto da estrarre nella cartella pubblica dell'hosting: il contenuto di dist/ sta alla radice dello zip, .htaccess compreso, senza cartelle di primo livello. Il dominio del sito è quello di site.config.mjs, oppure la variabile del repository SITE_URL se impostata (vedi «Configurazione»).

Quale file scaricare: a ogni release Gitea aggiunge da solo due archivi, «Source code (ZIP)» e «Source code (TAR.GZ)». Contengono il codice sorgente, non il sito: per metterlo online scegliere sempre lo zip sito-studio-grasso-vX.Y.Z.zip. La procedura di pubblicazione sull'hosting è in docs/DEPLOY.md.

Token: per impostazione predefinita la release è pubblicata con il token automatico del workflow. Se lo step di pubblicazione fallisce con errore 403 o 404, oppure per avviare in automatico il deploy facoltativo (docs/DEPLOY.md sezione 9: le azioni compiute con il token automatico non avviano altri workflow), creare un access token (Impostazioni utente → Applicazioni → Genera nuovo token, permesso write:repository) e salvarlo come segreto del repository RELEASE_TOKEN (Impostazioni del repository → Actions → Segreti): se esiste, il workflow lo usa al posto di quello automatico. I nomi di segreti e variabili non possono iniziare con GITEA_ o GITHUB_.

La release è pubblicata da scripts/release-upload.sh (solo curl e node) con l'API REST di Gitea, senza action esterne: crea la release in bozza, carica lo zip e solo allora la pubblica. Lo stesso script serve anche a mano (istruzioni in testa al file e in docs/DEPLOY.md).

Aggiornare le dipendenze

Le versioni sono bloccate (senza ^) e package-lock.json è committato. Per aggiornare: npm install <pacchetto>@<versione> --save-exact, poi npm run verify. Playwright: la versione di @playwright/test, playwright e playwright-core deve coincidere con l'immagine mcr.microsoft.com/playwright:vX.Y.Z-noble usata in .gitea/workflows/ci.yml e release.yml (oggi 1.56.1): aggiornandola, cambiare la versione in tutti e due i file.

Note

  • Le icone (favicon, og-default.png, logo) si rigenerano con npm run icons dopo modifiche al marchio; i file generati vanno committati.
  • Telemetria di Astro: disattivata in CI (ASTRO_TELEMETRY_DISABLED=1); in locale npx astro telemetry disable.
  • Caratteri Fraunces e Inter: SIL Open Font License 1.1; icone Lucide: licenza ISC.
S
Description
Sito internet per Studio Grasso
Readme
1.6 MiB
0 Stars 1 Watchers 0 Forks
v1.1.0
Latest
2026-11-13 11:27:20 +01:00
Languages
Astro 37.8%
TypeScript 31%
JavaScript 20.1%
CSS 5.8%
PHP 3.5%
Other 1.8%