Skip to content
Early bird + Black Friday · 73% off

Get ZeroDirs for $179 $49

Claim $49 deal

Environment and secrets

Everything configurable outside site.config.ts is a variable or a secret in .env.example, .env and .env.prod — the same keys in each, split by a marked line into the two halves below.

Above # === Runtime secrets === in .env.example. The # ci: line over each key tells pnpm cf:ci where it goes: variable, secret, or skip.

Variable Values Needed when cf:ci sends it as Page
CLOUDFLARE_ACCOUNT_ID the id pnpm exec wrangler whoami prints a production build, which reads the real database — all three, or none: with none set the build reads the local database, with one or two it fails a repository secret The build’s database
D1_DATABASE_ID database_id in wrangler.jsonc same a repository secret same
D1_READ_TOKEN an account API token with D1 › Read only — never the deploy token, and not named CLOUDFLARE_API_TOKEN same a repository secret; Workers Builds needs it as a build secret same
OG_RENDERER native (default) or wasm OG images where the native resvg binary cannot load nothing — .env only OG images

Below that line. pnpm cf:setup generates TOKEN_SECRET and sets it on the Worker; fill in the rest as you switch each feature on.

Secret What it is, and where from Read when Without it Page
TOKEN_SECRET 32+ random bytes, base64url; cf:setup generates it, by hand node -e "console.log(require('crypto').randomBytes(32).toString('base64url'))" always nothing can be signed: status links, checkout links; /submit/ refuses, and the placeholder is reported as an error Admin, Security
STRIPE_SECRET_KEY and STRIPE_WEBHOOK_SECRET a restricted key (rk_test_… in test mode), Checkout Sessions write only — Stripe → Developers → API keys → Create restricted key. The whsec_… comes with the endpoint https://<your site>/api/stripe/webhook/ (with the trailing slash) on checkout.session.completed and checkout.session.async_payment_succeeded features.payments on, providers.payment: 'stripe' checkout answers 503; /admin/ reports “Paid tiers cannot complete a checkout”; one without the other degrades the provider to none Plans and payments
RESEND_API_KEY re_…, sending-only — Resend → API Keys → Create → Sending access providers.email: 'resend' nothing leaves, yet each row is still marked sent; /admin/ reports the key missing (its line wrongly says mail is queued) Email
DEPLOY_HOOK_URL the URL is the credential — Workers & Pages → your Worker → Settings → Build → Deploy hooks providers.rebuild: 'deploy-hook' approvals trigger no build; /admin/ reports an error and offers “Publish now” Publishing on approval
GITHUB_TOKEN and GITHUB_REPO a fine-grained token (github_pat_…), Contents: Read and write on the repository that builds the site; owner/repo providers.rebuild: 'github-dispatch' the trigger falls back to none; approvals never publish same
GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET an OAuth client (Web application): id ending .apps.googleusercontent.com, secret beginning GOCSPX-, redirect URI https://<your site>/auth/google/callback/ features.accounts — optional no “Continue with Google” button; sign-in by emailed link still works. The one pair /admin/ does not flag Submitter accounts

cf:setup creates the first two in wrangler.jsonc; after a change there run pnpm cf:typegen, or pnpm check type-errors on the binding.

Binding Type Created by Needed for
DB D1 database cf:setup (wrangler d1 create) every listing the build renders, submissions, admin, accounts, the review queue, click counts, the D1 newsletter
MEDIA R2 bucket cf:setup (wrangler r2 bucket create) uploaded and seeded logos; media.baseUrl is the bucket’s custom domain
EMAIL send_email shipped in the file; cf:setup omits it until the account has a sending domain providers.email: 'cloudflare'
0 * * * * cron trigger shipped in the file the hourly jobs. A deploy without it clears the schedule

Fill in .env.prod, then send the lot in one request:

Terminal
cp .env .env.prod # the same keys, production values
pnpm cf:secrets --dry-run
pnpm cf:secrets

The dry run names every key, its value’s length, and why it skips one: empty (that provider stays off), a placeholder, or the wrong shape (a whsec_ in STRIPE_SECRET_KEY, a TOKEN_SECRET under 32 characters). A key .env.example does not know stops the run — a typo would otherwise become a secret nothing reads. Nothing uploads until you drop --dry-run; afterwards the command reads the Worker back and says what is set and what site.config.ts still needs. It never reads .env, so test-mode keys cannot reach production by accident, and it never echoes a value.

Only some of them:

Terminal
pnpm cf:secrets --list # the names, where each comes from, what is set
pnpm cf:secrets STRIPE_SECRET_KEY # only that one, from .env.prod
Where You should see
Everything pnpm cf:doctor cf:doctor — N ok, 0 warnings, 0 problems; every other line carries its fix
The Worker’s secrets pnpm cf:secrets --list, or pnpm exec wrangler secret list the names, never the values, set on the deployed Worker
What is missing https://<your site>/admin/ the configuration report: error = on but cannot work, warning = working differently than configured
The build’s database the build log [zerodirs-d1] D1 (remote): N approved listings on a builder, D1 (local) on your machine
  • Never put a secret in vars in wrangler.jsonc (deployed in plain text) or in the build-time half (reaches the HTML and the build log); D1_READ_TOKEN is the exception, read but never written out.
  • Wrong half, no error: a build-variable secret never reaches the Worker and /admin/ reports it missing; a D1 credential sent with cf:secrets never reaches the build, which on a builder then has none of the three and fails.
  • GitHub Actions also needs CLOUDFLARE_API_TOKEN (Edit Cloudflare Workers) and CLOUDFLARE_D1_WRITE_TOKEN (D1 Edit only), created once with gh secret set. Workers Builds needs neither.
  • pnpm cf:ci --enable sets the repository variable USE_GITHUB_DEPLOY=true, without which the shipped deploy.yml stays skipped — Deploy on git push.
  • .env.example the key set, both halves, with the instructions cf:secrets --list shows you
  • .env your machine, written from the example by pnpm dev; the three D1 credentials stay empty here so a local build reads the local database
  • .env.prod production values, read by cf:secrets and cf:ci
  • wrangler.jsonc the bindings and the cron trigger
  • astro.config.ts the env.schema that declares each secret context: 'server', access: 'secret'
  • Directoryscripts/
    • put-secrets.ts pnpm cf:secrets
    • cf-ci.ts pnpm cf:ci
    • cf-doctor.ts pnpm cf:doctor
  • Directorysrc/server/
    • env.ts the only reader of the secrets
    • secrets.ts configGaps(), the report /admin/ renders