Environment Variables
Configure local bindings, production inputs, OAuth, email, payments, and deployment secrets.
Separate local and deployment configuration
Flare does not consume the same environment variables as the Next.js starters. Configure the process that actually needs each value.
| Location | Consumer | Purpose |
|---|---|---|
apps/web/.dev.vars | Local Vite / Wrangler runtime | Local APP_URL, auth secret, optional integration keys |
Root .env | The muse CLI | Deployment account, production origin, authentication and integration secrets |
packages/cli/src/target-resources.ts | Deployment planner | Worker, D1, R2, queue, and dead-letter queue names |
The CLI loads root .env even for init. This does not automatically expose it to the local Vite runtime or make init a remote deployment command. Init creates or preserves the local auth secret and initializes local D1.
Prepare production inputs
Copy the committed example from the repository root:
cp .env.example .envReplace every placeholder with values for your own account:
CLOUDFLARE_ACCOUNT_ID=your-account-id
CLOUDFLARE_API_TOKEN=your-deployment-token
APP_URL=https://app.your-domain.com
AUTH_SECRET=replace-with-a-random-secret-at-least-32-characters
MAIL_FROM=Your Product <[email protected]>
ADMIN_EMAIL=[email protected]CLOUDFLARE_API_TOKEN is a deployment management credential, not an application API key. Keep it out of frontend variables, published excerpts, and browser bundles. Use at least 32 characters for AUTH_SECRET. Preserve an existing production value when moving machines or upgrading so that sessions remain valid.
APP_URL must be a single HTTPS origin without a path, query, fragment, credentials, or port. The CLI can derive a Workers subdomain when omitted; explicitly set the final origin for a custom domain so callbacks and Origin checks agree. ADMIN_EMAIL promotes a matching account only after registration and email verification; it does not seed a production user.
Understand precedence
Existing process variables win over root .env. Root .env wins over defaults from .muse/<target>.secrets.json. If an edit appears ineffective, check whether the terminal or CI already defines that key; avoid dumping all environment values.
Do not commit .env, .dev.vars, deployment state, or generated target configuration. A fresh Git checkout does not restore production credentials. Transfer required values through a secure channel when moving machines.
Enable integrations deliberately
| Integration | Variables | Additional setup |
|---|---|---|
GOOGLE_CLIENT_ID / GOOGLE_CLIENT_SECRET | Register /api/auth/callback/google | |
| GitHub | GITHUB_CLIENT_ID / GITHUB_CLIENT_SECRET | Register /api/auth/callback/github |
| Turnstile | TURNSTILE_SITE_KEY / TURNSTILE_SECRET | Allow the domain; keep the secret server-side |
| Stripe | STRIPE_SECRET_KEY / STRIPE_WEBHOOK_SECRET | Price mappings and signed webhooks |
| Creem | CREEM_API_KEY / CREEM_WEBHOOK_SECRET | Product mappings and signed webhooks |
| Dodo | DODO_API_KEY / DODO_WEBHOOK_SECRET | Matching environment, product IDs, and webhooks |
| Waffo | WAFFO_MERCHANT_ID / WAFFO_PRIVATE_KEY | One-line private key with \n escapes, product and signature setup |
| OpenAI | OPENAI_API_KEY | Default text, images and speech; muse:deploy uploads it as a Worker secret |
| Other AI models | DASHSCOPE_API_KEY / optional DASHSCOPE_HOST | Video and retained alternative image/speech models; uploaded as Worker secrets |
Local development switches
| Variable | Default | Effect |
|---|---|---|
FLARE_DEV_PORT | 3000 | Port for pnpm dev, local preview, the local APP_URL and Playwright. A value set in the terminal wins. |
AI_MODE | mock locally, live when deployed | live calls configured providers; mock makes no provider calls. |
WORKERS_AI_REMOTE | false locally | Set true after wrangler login only when testing Workers AI models; OpenAI does not need it. |
For local live calls, put OPENAI_API_KEY and any other required provider key in apps/web/.dev.vars. Root .env is the deployment CLI input, not the local Worker credential source. See AI overview.
Payment secrets alone do not enable checkout. Enable gateways and map products in packages/config. Email, AI, D1, R2, and Queues also require Worker bindings; an API token cannot replace a binding.
Verify and troubleshoot
pnpm muse:doctor --target production --json
pnpm muse:deploy --target production --plan --jsonResolve doctor blockers first. Review the account, target names, migrations, and creation actions in the plan. Plan mode does not create resources.
- Missing OAuth button: provide both values for that provider and inspect the public configuration from
/api/public/auth. - Production login fails: compare APP_URL, the browser origin, the production auth secret, and registered callback URLs.
- Local values stay stale: check process precedence and restart the development server.
- Workers Builds cannot find values: configure encrypted build environment variables; remote builds do not read your local .env.
Continue with deployment and payments.