Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_016zJ9ZWGKvoKoxYwbmnRKdJ
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 (solo file statici, con .htaccess) pronto per qualsiasi hosting.
- Requisiti di progetto:
docs/BRIEF.md· Mockup:docs/mockups/ - Decisioni tecniche:
DECISIONS.md· Dati da fornire:TODO-STUDIO.md· Novità:CHANGELOG.md - Pubblicazione sull'hosting:
docs/DEPLOY.md· Aggiornare i contenuti:docs/CONTENUTI.md· Conformità:docs/CONFORMITA.md
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 il pacchetto di rilascio in release/
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 + pacchetto in release/ + verifica del pacchetto (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: è il comando eseguito dalla CI.
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
tests/ e2e/ e a11y/ (Playwright), helpers/
deploy/ nginx.conf.example, optional-php-form/contact.php, esempio di deploy automatico
.forgejo/workflows ci.yml (verifica) e release.yml (pubblicazione della release)
docs/ brief, mockup, guide di deploy e contenuti, conformità
Configurazione
| Impostazione | Dove | Valore predefinito |
|---|---|---|
| Dominio del sito (canonical, sitemap, robots, dati strutturati) | variabile d'ambiente SITE_URL |
https://www.grassoezio.it |
Modulo di contatto: off, php, endpoint |
contactForm.mode 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 |
Esempio: SITE_URL=https://studiograssoezio.it npm run build.
Per verificare il modulo attivo (validazione, anti-spam, pagina di conferma):
CONTACT_FORM_MODE=php npm run build && npx playwright test tests/e2e/form.spec.ts && npm run build
Pubblicare il repository su Forgejo
Questo repository è un clone di https://forgejo.encke-hake.ts.net/BalboSoft/Studio_Grasso.git: il remote origin è già configurato. Per un repository nuovo: git remote add origin <url-del-repository>.
git push -u origin main # pubblica il codice: parte la CI (.forgejo/workflows/ci.yml)
Consigliato: proteggere il branch main (Impostazioni del repository → Branch → Protezione: niente push forzati, merge solo con CI verde) e lavorare con branch e pull request. I messaggi di commit seguono Conventional Commits in italiano (feat:, fix:, docs:, ci:, test:, chore:).
La CI richiede un runner Forgejo Actions con label docker (modificabile in cima ai file dei workflow). Le azioni sono indicate con URL completo su code.forgejo.org, quindi non dipendono dalla configurazione dell'istanza.
Fare una release
-
Aggiornare
versioninpackage.json(SemVer:1.0.1correzioni,1.1.0novità,2.0.0cambiamenti importanti) enpm installper allinearepackage-lock.json. -
Aggiungere in
CHANGELOG.mdla sezione## [X.Y.Z] - AAAA-MM-GG: diventa il testo della release. -
npm run verify, commit (chore(release): prepara vX.Y.Z) e push sumain. -
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: sito-studio-grasso-vX.Y.Z.zip, .tar.gz, SHA256SUMS.txt, BUILD-INFO.txt.
Token: su alcune istanze il token automatico dei workflow non può creare release. In quel caso creare un access token (Impostazioni utente → Applicazioni → Genera nuovo token, permesso write:repository) e salvarlo come segreto del repository con nome FORGEJO_TOKEN (Impostazioni del repository → Actions → Segreti): il workflow lo usa automaticamente. Se l'istanza rifiuta i nomi che iniziano con FORGEJO_, chiamarlo RELEASE_TOKEN. Lo stesso token serve per avviare in automatico il deploy facoltativo (docs/DEPLOY.md, sezione 9).
Il workflow pubblica la release con l'action forgejo-release; se l'action non riesce, lo step successivo la pubblica con l'API REST (scripts/release-upload.sh, solo curl e node). 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 .forgejo/workflows/ci.yml e release.yml (oggi 1.56.1).
Note
- Le icone (favicon,
og-default.png, logo) si rigenerano connpm run iconsdopo modifiche al marchio; i file generati vanno committati. - Telemetria di Astro: disattivata in CI (
ASTRO_TELEMETRY_DISABLED=1); in localenpx astro telemetry disable. - Caratteri Fraunces e Inter: SIL Open Font License 1.1; icone Lucide: licenza ISC.