NexStudio Website Runbook

Sito istituzionale NexStudio basato su Astro, con deploy su Cloudflare e form contatti protetto da Turnstile.

Obiettivo del repository

• Presentazione aziendale e servizi (homepage e pagine legali).
• Entry point unico per richieste commerciali e supporto.
• Base pronta per contenuti multilingua IT/EN/TH.
• Pipeline di deploy stabile su Cloudflare.

Stack tecnico

• Astro + Tailwind CSS
• Adapter Cloudflare (@astrojs/cloudflare)
• Sitemap (@astrojs/sitemap)
• Form backend su endpoint /api/contact
• Turnstile + Cloudflare Email Service per anti-spam e invio email

Struttura essenziale

• src/pages/: pagine pubbliche e route API (src/pages/api/contact.ts)
• src/components/: componenti UI condivisi
• src/data/: contenuti testuali e configurazioni pagine
• public/: asset statici (loghi, immagini, robots)
• .env.example: variabili locali di riferimento

Prerequisiti

• Node.js 20+
• npm 10+
• Account Cloudflare (Workers + Turnstile + Email Service con dominio onboardato, es. nexstudio.ai)

Avvio locale

1. Installazione dipendenze:
   • npm install
2. Copia variabili di ambiente:
   • copia .env.example in .env
3. Avvio sviluppo:
   • npm run dev
4. Se Vite resta in cache incoerente:
   • npm run dev:fresh

Comandi utili

• npm run dev: sviluppo locale
• npm run dev:fresh: reset cache .vite e .astro + avvio dev server
• npm run build: build produzione
• npm run preview: preview locale della build
• npm run deploy:cf: build + deploy con wrangler su output Astro

Configurazione contatti

Variabili pubbliche (frontend):

• PUBLIC_CONTACT_FORM_ACTION_URL (default consigliato: /api/contact)
• PUBLIC_CONTACT_FORM_SUCCESS_REDIRECT (URL assoluto della pagina post-submit)
• PUBLIC_CONTACT_FORM_MAILTO (fallback se action URL non disponibile)
• PUBLIC_CONTACT_TURNSTILE_SITE_KEY

Variabili server (Cloudflare/local):

• CONTACT_FORM_MODE (dev oppure live)
• CONTACT_FORM_FROM_EMAIL (consigliato: no-reply@nexstudio.ai, dominio verificato su Email Service)
• CONTACT_FORM_TO_EMAIL (default destinatario, es. info@nexstudio.ai)
• CONTACT_FORM_TO_EMAIL_INFO (opzionale, override esplicito per area "info")
• CONTACT_FORM_TO_EMAIL_PRIVACY
• CONTACT_FORM_TO_EMAIL_CAREERS
• CONTACT_TURNSTILE_SECRET_KEY

Comportamento:

• dev: accetta submit e scrive payload nei log (senza invio reale)
• live: valida Turnstile e invia email via binding EMAIL (Cloudflare Email Service)

Routing pubblico consigliato (portale vetrina):

• info: informazioni generali/commerciali
• privacy: richieste privacy e diritti interessato
• careers: candidature e collaborazioni

Indirizzi consigliati portale:

• info@nexstudio.ai
• privacy@nexstudio.ai
• careers@nexstudio.ai
• no-reply@nexstudio.ai (solo invio comunicazioni/newsletter, non destinazione inbound)

Configurazione newsletter

Sistema custom su Cloudflare D1 + Cloudflare Email Service (double opt-in).

Prerequisito: dominio (es. nexstudio.ai) onboardato in Email Service con SPF/DKIM, e binding send_email → EMAIL nel Worker.

Variabili server:

• NEWSLETTER_MODE (dev oppure live; se assente usa CONTACT_FORM_MODE)
• NEWSLETTER_FROM_EMAIL (fallback: CONTACT_FORM_FROM_EMAIL, consigliato no-reply@nexstudio.ai)
• NEWSLETTER_NOTIFY_TO_EMAIL (notifiche admin; fallback: CONTACT_FORM_TO_EMAIL)
• NEWSLETTER_ADMIN_TOKEN (Bearer token per endpoint admin)
• NEWSLETTER_TURNSTILE_SECRET_KEY (opzionale; fallback: CONTACT_TURNSTILE_SECRET_KEY)
• PUBLIC_SITE_URL (origine usata nei link di conferma/disiscrizione)

Endpoint pubblici:

• POST /api/newsletter/subscribe — iscrizione (form footer)
• GET /api/newsletter/confirm?token=… — conferma double opt-in
• GET|POST /api/newsletter/unsubscribe?token=… — disiscrizione

Endpoint admin (header Authorization: Bearer <NEWSLETTER_ADMIN_TOKEN>):

• GET /api/newsletter/admin/subscribers?status=active|pending|unsubscribed
• POST /api/newsletter/admin/send — body JSON { "subject", "text", "html?", "dryRun?" }

Nota: Email Service è pensato per email transazionali (conferme, contatti, notifiche). Le campagne marketing di massa non sono ancora il target ufficiale del servizio.

Database:

• D1 nexstudio-newsletter (binding NEWSLETTER_DB)
• Migrazioni in migrations/
• npm run db:migrate:local / npm run db:migrate:remote

Comportamento:

• dev: accetta submit e logga (senza D1/Email obbligatori)
• live: scrive su D1, invia email di conferma via Cloudflare Email Service, richiede binding D1 + EMAIL

Deploy Cloudflare

Impostazioni consigliate:

• Build command: npm run build
• Deploy command: npm run deploy:cf

Questa configurazione evita errori tipo: The entry-point file at "@astrojs/cloudflare/entrypoints/server" was not found.

Dominio e sicurezza

• Dominio ufficiale: https://nexstudio.ai
• Hostname Turnstile da mantenere allineati:
  • nexstudio.ai
  • www.nexstudio.ai (se usato)
  • localhost (test locale)
• Accesso pre-go-live gestito con Cloudflare Zero Trust Access

Stato operativo attuale

• Issue #1 (contact form live): implementata
• Issue #2 (anti-spam Turnstile): implementata
• Issue #3 (SEO base): implementata (sitemap, robots, canonical/OG/Twitter)
• Issue #4: in avanzamento (contenuti non placeholder)
• Issue #5: da completare (localizzazione reale IT/EN/TH)

Note operative

• Per modifiche non minori usare branch dedicato (feat/*, fix/*) e merge su main dopo verifica.
• Evitare commit su main per attivita complesse.
• Rigenerare eventuali API key esposte e aggiornare subito i secret su Cloudflare.