Configuration Guide

Core Concepts
D1 Setup

Configuration is split by responsibility so project-specific edits stay small and secrets stay out of the repo.

What Goes Where

Location Use for Examples
src/config/*.ts Source-level defaults and policies that app code imports. These are committed and typed. App name, default authenticated path, protected routes, app roles, permission values.
wrangler.jsonc vars Committed, non-secret Worker runtime values that can differ by deployed environment. EMAIL_PROVIDER, EMAIL_FROM, EMAIL_REPLY_TO, BETTER_AUTH_URL, MAILGUN_DOMAIN.
.dev.vars Local-only secrets and local-only overrides. Never commit this file. BETTER_AUTH_SECRET, local BETTER_AUTH_URL, RESEND_API_KEY, MAILGUN_API_KEY, local email overrides.
Wrangler secrets Deployed secret values managed by Cloudflare, not committed to git. BETTER_AUTH_SECRET, RESEND_API_KEY, MAILGUN_API_KEY.

This separation of concerns keeps editable source policy in src/config, runtime environment selection in Wrangler config, and secret material outside committed files.

Source Config

Use src/config when changing values that the app code should import directly:

  • src/config/app.ts: app identity and default navigation paths.
  • src/config/auth.ts: middleware route policy, admin route policy, app roles, app permission values, and banned-session copy.

Database target constants stay with src/db/target.ts. Email provider names and fallback behavior stay with src/email. Do not put environment secrets here. Do not move database schema here; schema belongs in src/db/schema.

Worker Runtime Config

Use wrangler.jsonc for non-secret values the Worker reads from env:

{
  "vars": {
    "EMAIL_PROVIDER": "console"
  }
}

Named Wrangler environments need their own vars block because Wrangler does not inherit top-level vars into environments.

Local And Deployed Secrets

Use .dev.vars for local development secrets:

BETTER_AUTH_SECRET=replace-with-at-least-32-random-characters
BETTER_AUTH_URL=http://localhost:4321
RESEND_API_KEY=your-local-resend-key
MAILGUN_API_KEY=your-local-mailgun-key
MAILGUN_DOMAIN=mg.example.com

Use Wrangler secrets for deployed secrets:

npx wrangler secret put BETTER_AUTH_SECRET
npx wrangler secret put RESEND_API_KEY
npx wrangler secret put MAILGUN_API_KEY

Wrangler prompts for each value without storing it in the repo. If you deploy a named environment, pass the environment name:

npx wrangler secret put BETTER_AUTH_SECRET --env production

Only configure provider-specific secrets for the email provider the environment actually uses.