Environment Variables

The template has five configuration planes. Keeping them separate prevents the most common Cloudflare deployment mistakes.

Configuration planes

Why .env works locally

@cloudflare/vite-plugin loads local variables for the Worker environment while Vite also exposes VITE_* values through import.meta.env. That makes .env the single file for normal pnpm dev work. If you run wrangler dev directly, .dev.vars can be used as a fallback.

Neither .env nor .dev.vars is uploaded by wrangler deploy. Production gets bindings and non-secret vars from wrangler.jsonc, server secrets from wrangler secret put, and VITE_* values from the environment that runs the build.

Core authentication

Safe local example:

BETTER_AUTH_SECRET=generate-a-real-random-value
BETTER_AUTH_URL=http://localhost:3000

Production wrangler.jsonc keeps the URL as a non-secret var:

"vars": {
	"BETTER_AUTH_URL": "https://app.example.com"
}

Set the secret separately:

pnpm wrangler secret put BETTER_AUTH_SECRET

OAuth providers

Set both values for each enabled provider. If a provider is not configured, remove or hide its UI button. Callback URLs are covered in Authentication.

Email and AI

These are Worker secrets in production. See Email, AI Chat, and AI Media for feature setup and hardening.

Creem payments

Server-only runtime values

The production setup uses wrangler secret put for all three so they remain server-only.

Build-time product IDs

These IDs are read by src/config/price-config.ts and inlined by Vite. They are not Worker secrets. A changed product ID has no effect until you rebuild and redeploy. See Payments.

Application flags

Like every VITE_* value, this is visible in the built client and must not contain a secret.

D1 and R2 bindings

Bindings are declared in wrangler.jsonc:

"d1_databases": [
	{
		"binding": "DB",
		"database_name": "soar-tanstack",
		"database_id": "replace-with-your-d1-id",
		"migrations_dir": "drizzle"
	}
],
"r2_buckets": [
	{ "binding": "UPLOADS", "bucket_name": "soar-tanstack-uploads" }
]

Application code imports env from cloudflare:workers and reads env.DB or env.UPLOADS inside request-time factories/handlers. Do not replace this with process.env.DB, and do not capture a binding during top-level module evaluation.

Drizzle Kit remote credentials

drizzle.config.ts uses these only for Drizzle Kit commands that contact D1 over its d1-http driver. It explicitly loads .env.local; exporting the values in your shell also works. pnpm db:generate is offline, and the template's pnpm db:migrate uses Wrangler, so app runtime does not need these credentials.

Production secret setup

Run each command and enter the value interactively:

pnpm wrangler secret put BETTER_AUTH_SECRET
pnpm wrangler secret put GITHUB_CLIENT_ID
pnpm wrangler secret put GITHUB_CLIENT_SECRET
pnpm wrangler secret put GOOGLE_CLIENT_ID
pnpm wrangler secret put GOOGLE_CLIENT_SECRET
pnpm wrangler secret put RESEND_API_KEY
pnpm wrangler secret put OPENAI_API_KEY
pnpm wrangler secret put REPLICATE_API_TOKEN
pnpm wrangler secret put CREEM_API_KEY
pnpm wrangler secret put CREEM_WEBHOOK_SECRET
pnpm wrangler secret put CREEM_SERVER_IDX

Only set secrets for features you intend to enable. Never commit real values to .env.example or wrangler.jsonc.

Related pages