For AI agents: fetch the complete documentation index at /llms.txt, the full documentation corpus at /llms-full.txt, the agent skill at /skill.md, or this page as Markdown at /it/docs/modules/config.md (or send Accept: text/markdown).
Ambiente e configurazione
Uno schema validato unico per tutto il workspace.
Apportare una modifica alla configurazione e controllarla
Inizia con un'app Web in esecuzione. Nell'editor apri apps/web/.env.local; se non esiste, copia lì .env.example utilizzando il tutorial Web. Per un primo controllo innocuo, trova EMAIL_PROVIDER=local e lascialo locale. Questa impostazione invia l'e-mail del prodotto all'anteprima locale anziché a una casella di posta reale. Non incollare le linee KEY=value nel terminale.
Per ogni servizio che abiliti, segui la guida di installazione del provider, sostituisci solo i valori nominati, salva il file, arresta il server Web con Ctrl + C e riavvia con il comando seguente. Se la convalida nomina una chiave mancante, riapri questo file e confronta quella chiave con la guida del provider. Mantieni sincronizzato root .env solo per i valori utilizzati dalle migrazioni del database; copiarlo da solo non configura Next.js.
corepack pnpm --filter @supastack/web devInizia dall'esempio di ambiente
Il .env.example radice è l'inventario di configurazione. La validazione condivisa vive in packages/config. Rivedi insieme l'ambiente applicativo scelto e le modalità dei provider; un'interfaccia locale non è una strategia di credenziali di produzione.
La modalità di riferimento senza credenziali richiede una configurazione applicativa local/test e provider fake/locali. Scegliere un provider di produzione cambia i requisiti del runtime.
Tieni i segreti dietro l'API
Segreti di auth, credenziali del database, chiavi dei provider, segreti Stripe e credenziali Trigger sono solo server. Non dare loro mai il prefisso NEXT_PUBLIC_ o EXPO_PUBLIC_. Non mostrarli durante l'installazione e non includerli nelle risposte di errore.
Il browser riceve la configurazione pubblica e gli alias di modello consentiti. Possesso del workspace, decisioni sui permessi, budget e scelta del provider restano applicati lato server.
Verifica una modifica prima di usarla
Valida la configurazione tramite il pacchetto config esistente ed esegui i test deterministici pertinenti. Usa il percorso di smoke dei provider opt-in separato quando sei pronto a verificare integrazioni reali.
corepack pnpm test
corepack pnpm check
corepack pnpm buildInstallazione e configurazione
packages/config è l'unico posto che parsa process.env: uno schema zod produce un ServerConfig e un PublicConfig tipizzati, e la selezione dei provider si esprime come kinds — providers.ai, providers.billing, providers.email, providers.jobs, providers.storage si risolvono ciascuno in un adattatore nominato più i suoi campi richiesti.
Abilitare un provider rende le sue credenziali richieste: attivare un social sign-in, il kind storage s3 o il kind email resend fa fallire l'avvio nominando la variabile mancante, invece di una sorpresa runtime più tardi.
STORAGE_PROVIDER=s3
STORAGE_BUCKET=kit
STORAGE_ENDPOINT=https://s3.example
STORAGE_PUBLIC_BASE_URL=https://cdn.example
# → config rejects the env if a required field is missingFlusso di implementazione
Leggi la config tramite parseServerConfig al confine server e passa il valore tipizzato verso l'interno — non toccare process.env dentro il codice delle feature. La config pubblica è un oggetto separato, deliberatamente piccolo, sicuro da serializzare al client.
L'env specifico del prodotto appartiene allo schema proprio del prodotto consumatore. Resisti al far crescere lo schema del kit per le esigenze di un solo prodotto.
Verifica e risoluzione dei problemi
Esegui i test del package config dopo aver cambiato lo schema, e controlla che una variabile richiesta mancante si nomini nell'errore. Un env che parsa in locale ma non in produzione di solito significa un campo richiesto non documentato.