Environment Variables
This page is a navigation index to help you locate detailed env-var docs by module.
This page is intentionally an index: verify minimum required variables first, then jump to module-specific docs for full setup.
How to Read This Page
Use this as a routing index: verify minimum variables first, then jump to module-specific docs for full setup.
Minimum Required Variables
| Variable | Purpose | Required |
|---|---|---|
NEXT_PUBLIC_SITE_URL | Public site URL for links and callbacks | Yes |
DATABASE_URL | Database connection string | Yes |
BETTER_AUTH_SECRET | Better Auth signing/session secret | Yes |
DATABASE_CONNECTION_STRATEGY | DB connection priority strategy | No (default hyperdrive_first) |
Startup Validation
Server environment variables are validated at startup: src/lib/env.ts runs via the register() hook in src/instrumentation.ts. In a production runtime, a missing BETTER_AUTH_SECRET throws immediately at startup so the deployment fails fast (next build and local dev are not affected). The following cases log non-fatal warnings instead: an enabled billing gateway missing its webhook secret (webhooks are rejected in production), DATABASE_CONNECTION_STRATEGY=database_url_first without DATABASE_URL, and MAIL_PROVIDER=resend without RESEND_API_KEY.
Database Connection Strategy (Short)
# Recommended on Cloudflare Worker
DATABASE_CONNECTION_STRATEGY="hyperdrive_first"
# Prefer local/explicit DATABASE_URL first
# DATABASE_CONNECTION_STRATEGY="database_url_first"hyperdrive_first: Hyperdrive first, fallback toDATABASE_URLdatabase_url_first:DATABASE_URLfirst, fallback to Hyperdrive
Runtime Strategy
Prefer hyperdrive_first on Cloudflare Workers, and switch to database_url_first only when your environment requires it.
Module Navigation Matrix
| Module | Key Variables (Examples) | Summary | Detailed Doc |
|---|---|---|---|
| Authentication | BETTER_AUTH_SECRET, GITHUB_CLIENT_ID, GOOGLE_CLIENT_ID | Login/session and OAuth provider setup | /docs/permissions/permission-architecture |
RESEND_API_KEY | Email delivery channel for auth and notifications | /docs/mail-system | |
| Billing (Creem) | MUSE_CREEM_GATEWAY_API_KEY, MUSE_CREEM_GATEWAY_WEBHOOK_SECRET | Creem gateway + webhook configuration | /docs/muse-billing/muse-creem-gateway |
| Billing (Stripe) | MUSE_STRIPE_GATEWAY_SECRET_KEY, MUSE_STRIPE_GATEWAY_WEBHOOK_SECRET | Stripe gateway + webhook configuration | /docs/muse-billing/muse-stripe-gateway |
| Storage | S3_ACCESS_KEY_ID, S3_SECRET_ACCESS_KEY, S3_ENDPOINT | S3-compatible upload and signed URLs | /docs/storage-module |
| Analytics | (project-specific) | Tracking script and event strategy | /docs/site-analytics |
| Deployment Strategy | DATABASE_CONNECTION_STRATEGY | DB routing strategy across runtimes | /docs/deployment/deployment-targets |
Example: How to Configure Resend API Key
RESEND_API_KEY is used to authenticate mail delivery.
RESEND_API_KEY="re_xxx"For the full mail pipeline, templates, and i18n behavior, see:
Management Rules
Never commit real secrets.
Add every new variable to .env.local.example.
Keep production values isolated from staging/local values.