Configurazione

Apportare una modifica alla configurazione e controllarla

Inizia con un'app Web in esecuzione. Nell'editor apri apps/web-tanstack/.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 TanStack Start.

• Cerca una chiave di configurazione
• Scopri come eseguire un comando e modificare un file

corepack pnpm --filter @supastack/web-tanstack dev

Le impostazioni che modificherai davvero per prime

.env.example alla radice del repository è l'inventario completo delle impostazioni che il kit conosce; un nome assente da quel file non esiste. All'inizio ne tocchi solo una manciata — le altre restano ai loro default finché una guida dei provider non le richiede.

Quale file legge ogni app: .env alla radice alimenta i comandi di migrazione, apps/web-tanstack/.env.local alimenta il server TanStack Start e apps/mobile/.env.local alimenta Expo. Modificare un file non configura gli altri, quindi DATABASE_URL vive sia in .env alla radice sia in apps/web-tanstack/.env.local.

• APP_URL — l'indirizzo dove vive l'app; http://localhost:3000 in locale, il tuo dominio in produzione.
• DATABASE_URL — la stringa di connessione Postgres che migrazioni e server condividono.
• AUTH_SECRET e CREDENTIAL_ENCRYPTION_KEY — segreti generati; node scripts/setup-env.mjs li compila per te (quell'helper è incluso nel repository web TanStack e nel monorepo All Platforms).
• I selettori dei provider — EMAIL_PROVIDER, AI_PROVIDER, BILLING_PROVIDER, JOB_PROVIDER, CAPTCHA_PROVIDER — ciascuno sceglie quale adapter viene eseguito; i default local/fake/off non richiedono alcun account.
• Segreti dei provider come RESEND_API_KEY o STRIPE_SECRET_KEY — aggiungili solo quando la guida del provider corrispondente te lo dice.

Inizia 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 build