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 |
MUSE_SETTINGS_SECRET | Wrapping key for encrypted payment and storage settings in the database | Yes (min 32 characters) |
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 or MUSE_SETTINGS_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: DATABASE_CONNECTION_STRATEGY=database_url_first without DATABASE_URL, and MAIL_PROVIDER=resend without RESEND_API_KEY. Payment and storage credentials are not env vars — configure them at /app/admin/settings. See Runtime Settings.
Generate MUSE_SETTINGS_SECRET
Do not reuse the placeholder from .env.local.example. Generate a unique wrapping key (at least 32 characters), for example openssl rand -hex 32. This secret encrypts payment and storage settings in the database and is never stored there.
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 | Admin settings (not env) | Gateway credentials and checkout product IDs live at /app/admin/settings | /docs/admin/runtime-settings |
| Storage | NEXT_PUBLIC_AVATARS_PROXY_URL (S3 credentials are admin settings) | Proxy URL stays in env; S3 keys and bucket are stored in the database | /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. Generate MUSE_SETTINGS_SECRET with openssl rand -hex 32 (at least 32 characters).
Add every new variable to .env.local.example.
Keep production values isolated from staging/local values.
Payment gateway and S3 credentials belong in /app/admin/settings, not in env.