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.
Build-time variables
Section titled “Build-time variables”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 |
Runtime secrets
Section titled “Runtime secrets”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) |
|
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 |
Bindings
Section titled “Bindings”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 |
Putting secrets in
Section titled “Putting secrets in”Fill in .env.prod, then send the lot in one request:
cp .env .env.prod # the same keys, production valuespnpm cf:secrets --dry-runpnpm cf:secretsThe 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:
pnpm cf:secrets --list # the names, where each comes from, what is setpnpm cf:secrets STRIPE_SECRET_KEY # only that one, from .env.prodVerify
Section titled “Verify”| 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 |
Worth knowing
Section titled “Worth knowing”- Never put a secret in
varsinwrangler.jsonc(deployed in plain text) or in the build-time half (reaches the HTML and the build log);D1_READ_TOKENis 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 withcf:secretsnever 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) andCLOUDFLARE_D1_WRITE_TOKEN(D1 Edit only), created once withgh secret set. Workers Builds needs neither. pnpm cf:ci --enablesets the repository variableUSE_GITHUB_DEPLOY=true, without which the shippeddeploy.ymlstays skipped — Deploy on git push.
- .env.example the key set, both halves, with the instructions
cf:secrets --listshows 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:secretsandcf:ci - wrangler.jsonc the bindings and the cron trigger
- astro.config.ts the
env.schemathat declares each secretcontext: 'server', access: 'secret' Directoryscripts/
- put-secrets.ts
pnpm cf:secrets - cf-ci.ts
pnpm cf:ci - cf-doctor.ts
pnpm cf:doctor
- put-secrets.ts
Directorysrc/server/
- env.ts the only reader of the secrets
- secrets.ts
configGaps(), the report/admin/renders