Configurazione

Ogni variabile vive in .env.example con i commenti accanto. Copialo in .env.local e riempi quello che ti serve: ogni funzione si accende quando le sue variabili sono impostate, e resta spenta in silenzio quando non lo sono.

Database

Nucleo dell'autenticazione

Provider OAuth

Entrambi i provider sono facoltativi. Un pulsante compare nella pagina di accesso, e nelle impostazioni, solo quando entrambe le chiavi del suo provider sono impostate: configura quelli che vuoi e riavvia il server di sviluppo.

Google (console.cloud.google.com → APIs & Services → Credentials → OAuth 2.0 Client ID)

• URI di reindirizzamento autorizzato: http://localhost:3000/api/auth/callback/google (ripeti col tuo dominio di produzione quando pubblichi)
• Copia client ID e secret in GOOGLE_CLIENT_ID e GOOGLE_CLIENT_SECRET

GitHub (github.com/settings/developers → OAuth Apps → New OAuth App)

• URL di callback: http://localhost:3000/api/auth/callback/github
• Copia i valori in GITHUB_CLIENT_ID e GITHUB_CLIENT_SECRET

Email (Resend)

Come si prepara: apri un account su resend.com, verifica il dominio, crea una chiave API. Un altro provider (SMTP, Postmark, SES): vedi Email.

La verifica del dominio su Resend imposta SPF e DKIM, non una politica DMARC. Aggiungi anche un record DMARC dal tuo provider DNS, un record TXT su _dmarc.iltuodominio.com come v=DMARC1; p=quarantine; rua=mailto:tu@iltuodominio.com: senza, alcuni provider di posta mettono le email transazionali nello spam, e nessuno dice ai server che le ricevono cosa fare con la posta che si finge spedita dal tuo dominio.

Quando un'email non arriva, guarda nei log. Resend può rifiutare un messaggio che il kit gli ha passato: il dominio mittente non è ancora verificato, la quota giornaliera del piano è finita, oppure il destinatario è nella lista di soppressione di Resend. Ogni rifiuto viene scritto nei log come [email] <tipo> rejected by Resend, con il motivo e il codice di Resend, e mai con l'indirizzo del destinatario. Il modulo contatti avvisa il visitatore quando il suo messaggio non è partito. Il reset della password, il link magico, il cambio email e l'iscrizione alla newsletter invece no, di proposito: rispondono allo stesso modo che un indirizzo sia registrato o no, così nessuno li può usare per scoprire chi ha un account, e un errore visibile in caso di rifiuto annullerebbe questa protezione. Con un dominio non verificato viene rifiutata ogni email fin dalla prima, ed è quindi la causa più probabile su un deploy nuovo.

Un caso richiede una persona invece di una correzione: un contatto che si disiscrive viene tolto anche dall'audience di Resend, e se Resend rifiuta la rimozione la riga di log lo dice, perché un broadcast spedito da Resend lo raggiungerebbe lo stesso. Toglilo a mano prima del prossimo invio.

Stripe

1. Apri un account su stripe.com e copia la Secret key in STRIPE_SECRET_KEY (e la publishable key in NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY).

2. Crea prodotti e prezzi nel pannello Stripe. Il seed include sei piani di esempio (Starter e Pro nelle varianti mensile e annuale, un piano Lifetime una tantum, e un esempio a consumo disattivo) così il checkout funziona subito; sostituiscili coi tuoi.

3. Copia gli ID dei prezzi in STRIPE_STARTER_PRICE_ID, STRIPE_STARTER_YEARLY_PRICE_ID, STRIPE_PRO_PRICE_ID, STRIPE_PRO_YEARLY_PRICE_ID e STRIPE_LIFETIME_PRICE_ID (oppure modifica prisma/seed.ts), poi lancia npx prisma db seed. STRIPE_METERED_PRICE_ID serve solo se attivi l'esempio a consumo (vedi Pagamenti).

4. Webhook in locale, con la Stripe CLI:

   TerminalCopy

   stripe listen --forward-to localhost:3000/api/webhooks/stripe

   Copia il signing secret in STRIPE_WEBHOOK_SECRET. I webhook di produzione sono in Deployment; come funzionano i flussi di pagamento (abbonamenti, una tantum, a consumo) è in Pagamenti.

Due interruttori facoltativi, spenti finché non valgono "true":

Limitazione delle richieste

Sono facoltative di proposito: una variabile obbligatoria avrebbe reso una major, per chiunque avesse già clonato il kit, la release che ha aggiunto questa funzione. Impostandole non cambia nient'altro, non viene installata nessuna libreria client, e se l'archivio è configurato ma irraggiungibile il limitatore ricade sul contatore in memoria invece di fallire in una delle due direzioni.

Vale la pena sapere quale limite spostare per primo, perché non proteggono la stessa cosa. Il limite sull'accesso protegge i tentativi di password, e lì il costo di bcrypt porta gran parte del peso. I limiti su magic link, registrazione e reset proteggono l'invio di email: ognuno stabilisce quanti messaggi può innescare un singolo indirizzo, e bcrypt non c'entra niente. Se quello che stai proteggendo è la bolletta di Resend o la tua reputazione da mittente, è quello che guadagna di più da un archivio condiviso. Il resto sta in Autenticazione.

Interruttori ed extra

Due distribuzioni da un solo codice

KIT_SITE esiste perché openstarterkit.dev e il kit che hai clonato sono un repository solo. L'alternativa era una seconda copia del sito di marketing, e una copia si allontana: il giorno che sistemassimo qualcosa sul sito, quello smetterebbe di essere il codice che cloni.

Accenderlo nella tua app ti dà il nostro sito, non un suo modello. Il nostro titolo, i nostri livelli open source e la waitlist Pro al posto delle tue righe Plan, le FAQ sulla licenza, i link MIT nel footer, e il nostro nome e indirizzo di contatto ovunque tu non abbia impostato le variabili del marchio. Spento è lo stato che vuoi, e spento è il valore predefinito.

Il meccanismo che ci sta sotto invece vale la pena averlo, ed è la parte che è tua. Le sezioni che si leggono diversamente fra due distribuzioni portano entrambe le varianti sotto $kit e $product nei file dei messaggi, e il build butta via quella che non può rendere, così nessuna delle due si porta dietro il testo dell'altra. Rinomina l'interruttore, metti le tue parole sotto i marcatori, e hai un sito di marketing e un'app su due domini da un repository solo, che divergono solo dove devono. I dettagli sono in Lingue.

Se quello che vuoi è una seconda distribuzione per mostrare il prodotto, quella è DEMO_MODE, non questa: account condivisi a un clic, OAuth reale spento, un ripopolamento giornaliero, e la tua app intatta sul suo dominio.

Consenso ai cookie

Di serie non c'è niente per cui chiedere il consenso: l'unico cookie è quello della sessione, strettamente necessario, e Vercel Analytics non usa cookie. Per questo il banner parte spento, e la pagina /cookies d'esempio dice che non serve.

Accendilo il giorno in cui aggiungi qualcosa che imposta cookie o traccia i visitatori: Google Analytics, un pixel pubblicitario, una chat. Imposta NEXT_PUBLIC_COOKIE_CONSENT="true" e carica quegli script con <ConsentScript> al posto di next/script:

import { ConsentScript } from "@/components/consent/consent-script"

<ConsentScript src="https://www.googletagmanager.com/gtag/js?id=G-XXXX" strategy="afterInteractive" />

Uno script avvolto così parte solo dopo che il visitatore ha scelto Accept. Con la variabile spenta <ConsentScript> è un normale next/script, quindi usarlo non costa niente finché non serve.

Cosa fa il banner, seguendo le linee guida 2021 del Garante, fra le più severe in Europa: Accept e Reject hanno lo stesso aspetto, chiuderlo vale come rifiuto, lo scroll non è consenso, e non copre la pagina. La scelta resta salvata per sei mesi in un cookie tecnico, cookie_consent, e Cookie settings riapre il banner. Quando un visitatore ritira il consenso la pagina si ricarica, perché uno script già partito non si può scaricare; i cookie che ha impostato tocca a lui cancellarli. Con la variabile accesa la pagina /cookies descrive anche i cookie facoltativi: adattala a quello che carichi davvero.

Preferisci nessun banner? Usa analytics senza cookie, come Vercel Analytics (già nel kit) o Plausible, e lascia la variabile spenta. Ti servono le categorie (analytics e marketing separati)? Il banner è un sì o un no unico, adatto a una finalità sola. Se carichi script per finalità diverse o di più terze parti, il Garante chiede anche di poterli scegliere uno per uno, quindi aggiungi le categorie prima di andare online. Il banner è un solo componente in src/components/consent/, abbastanza piccolo da estendere; per una gestione completa del consenso, vanilla-cookieconsent è un'opzione open source matura.

Marchio e tema

Il kit arriva neutro: un nome segnaposto e un tema nero con scala di grigi, così si legge come una tela bianca da fare tua. Ci sono due modi per rifarne il marchio.

Dalla configurazione (modificando il codice):

• src/config/site.ts: nome, tagline, descrizione, email di contatto, link
• src/components/logo.tsx: il simbolo del logo (cambia l'icona); la scritta segue siteConfig.name
• src/app/icon.tsx: la favicon, disegnata con lo stesso simbolo e generata al build, quindi non c'è nessun .ico da ridisegnare. Prende da sola il tuo colore d'accento; cambia il fulmine qui quando cambi il simbolo del logo.
• src/app/globals.css: i token di colore sotto :root e .dark (--primary, --primary-2, --gradient-brand)
• src/app/globals.css: gli sfondi decorativi dell'hero, .bg-grid (griglia tenue) e .bg-glow (alone d'accento). Sono puramente estetici, quindi svuotare una regola li toglie ovunque siano usati: hero della landing, pagine di accesso e 404.

Dall'ambiente (senza toccare il codice): ogni campo ha un valore neutro di ripiego, quindi imposta solo quello che vuoi cambiare.

Il codice è MIT, quindi usalo per qualsiasi cosa. Il badge «Built with» nel footer è facoltativo (NEXT_PUBLIC_REMOVE_BRANDING="true").

SEO

Buona parte è già collegata, e segue il tuo marchio invece di chiedere di ripetere le stesse cose:

• Titoli e descrizioni per pagina, con NEXT_PUBLIC_SEO_TITLE visto sopra per la home quando il titolo cercabile e lo slogan leggibile non coincidono
• Indirizzi canonici sulla home, su /pricing, /blog, /docs e su ogni articolo, costruiti da NEXT_PUBLIC_APP_URL. Imposta quella variabile in produzione: senza, ricade su localhost e ogni canonico punta a una macchina che nessuno può raggiungere
• Dati strutturati: Organization e FAQPage sulla home, Article su ogni articolo. Il markup delle FAQ è generato dalle stesse domande che modifichi in src/components/landing/faq.tsx, quindi rispondere per il tuo prodotto aggiorna entrambe le cose insieme
• sitemap.xml e robots.txt generati dal codice, con le bozze escluse
• /llms.txt, che descrive il sito alle macchine che lo riassumono, a partire da nome, descrizione e contenuti. NEXT_PUBLIC_LLMS_SUMMARY ci aggiunge in cima una frase tua: di' cosa fai e per chi, con le parole che userebbe chi lo sta cercando

La sezione FAQ rende su più di una pagina, quindi i dati strutturati vengono emessi solo dove si usa <FAQ withJsonLd />, che di default è la home. Se la sposti, sposta anche il flag e tienilo su una pagina sola: la stessa FAQ pubblicata sotto più indirizzi vale meno che sotto uno solo.