Deployment
Environment variables reference Every env var the boilerplate reads, what it does, and what happens when it is unset.
Every external provider is optional and degrades gracefully . There is no
required external service for local dev. In production, you set the keys for
the providers you actually use; the rest no-op without breaking the app.
The full canonical list lives in
.env.example
Var Required Default Behavior when unset DATABASE_URLProduction yes (PGlite local) Local dev uses PGlite on localhost:5433.
Var Required Default Behavior when unset NEXTAUTH_SECRETProduction yes — Sessions can't be signed. Sign-in fails. NEXTAUTH_URLProduction yes http://localhost:3000OAuth callbacks build wrong URLs. GITHUB_CLIENT_ID / GITHUB_CLIENT_SECRETNo — GitHub OAuth button hides. GOOGLE_CLIENT_ID / GOOGLE_CLIENT_SECRETNo — Google OAuth button hides.
Var Required Default Behavior when unset RESEND_API_KEYNo — Email.* calls log HTML to stdout instead of sending.EMAIL_FROMNo no-reply@example.com— EMAIL_FROM_NAMENo Next.js BoilerplateUsed as sender display + brand in templates.
Var Required Default Behavior when unset STRIPE_SECRET_KEYNo — Checkout dispatch fails; buttons stay visible. STRIPE_WEBHOOK_SECRETNo — Webhook handler 200s without firing audit events (dev safety). NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEYNo — Stripe.js can't init client-side. STRIPE_PRICE_PRO_MONTHLY etc.Per-tier — Subscription sign-ups for that tier no-op.
See architecture/billing for the full webhook
flow.
Var Required Default Behavior when unset ANTHROPIC_API_KEYNo — Claude calls throw LlmProviderKeyMissing. OPENAI_API_KEYNo — GPT calls throw LlmProviderKeyMissing. OLLAMA_BASE_URLNo — Local LLM calls throw same error.
The visible-error contract per repo rules — no silent fallback, the missing
env var name is in the error.
Var Required Default Behavior when unset STORAGE_PROVIDERNo localRGPD exports + uploads write to ./local-storage/. STORAGE_S3_*If STORAGE_PROVIDER=s3 — Uploads fail with explicit error. STORAGE_R2_*If STORAGE_PROVIDER=r2 — Same as above.
Var Required Default Behavior when unset NEXT_PUBLIC_SENTRY_DSN / SENTRY_AUTH_TOKENNo — Sentry no-ops; no source map upload. NEXT_PUBLIC_SENTRY_DISABLEDNo — Set to disable Sentry entirely (CI / preview). NEXT_PUBLIC_POSTHOG_KEY / NEXT_PUBLIC_POSTHOG_HOSTNo — PostHog client no-ops. ARCJET_KEYNo — Bot detection middleware short-circuits.
Var Required Default Behavior when unset SECURITY_CONTACT_EMAILNo security@example.comUsed in /.well-known/security.txt. SECURITY_POLICY_URLNo ${origin}/security-policy—
Var Required Default Behavior when unset MAINTENANCE_MODENo 0When 1, every route except allow-list redirects to /maintenance. MAINTENANCE_ETANo — Free-form string shown on /maintenance. MAINTENANCE_STATUS_URLNo — Link from /maintenance to status page. MAINTENANCE_CHANGELOG_URLNo — Link from /maintenance to "what changed".
Var Required Default Behavior when unset JOBS_PROVIDERNo localUses the in-process local job bus. For production workers, choose railway, cloudflare-queues, or trigger. RAILWAY_WORKER_URL / RAILWAY_WORKER_TOKENRequired when JOBS_PROVIDER=railway — Railway dispatch throws a visible configuration error instead of dropping jobs. CLOUDFLARE_QUEUE_PRODUCER_URLRequired when JOBS_PROVIDER=cloudflare-queues — Cloudflare queue dispatch throws a visible configuration error. TRIGGER_API_KEY / TRIGGER_PROJECT_IDRequired when JOBS_PROVIDER=trigger — Trigger.dev dispatch throws a visible configuration error.
# Print every env var the app actually reads at boot. # (Drops to stderr in dev so you can pipe it.) NEXT_DEV_ENV_DUMP = 1 npm run dev The Env.ts library validates every var at boot using zod. A misconfigured
var fails fast with a typed error pointing at the var name and expected shape.
Don't commit .env.production to the repo. Vercel / Cloudflare / Fly all
provide an env-var dashboard. The repo only ever sees .env.example
(committed) and .env.local (gitignored, dev only).