Production Deploys

Deploy production to your own Cloudflare account: API token, first deploy, Worker secrets, Workers Builds, branch protection, rollback and DATABASE_URL.

Production deploys from main to the Worker web on your Cloudflare account. You set it up in this order: the first deploy runs from your machine, then Workers Builds takes over.

This page is part of the Deployment documentation.

Before You Start

  • A Cloudflare account on Workers Paid ($5/month), with a workers.dev subdomain (Workers & Pages → your subdomain, for example my-team). The kit needs Paid to run reliably: Free can't send email to your users (verification, password reset), and password hashing at sign-in and sign-up can exceed Free's 10 ms CPU limit.
  • Your email sender set in apps/web/void.config.ts (email: { from: 'Acme <noreply@mail.acme.com>' }), on a domain in your Cloudflare account; a mail subdomain keeps existing mail on the root domain. The first deploy offers to set up Email Sending for it; if it needs onboarding after upgrading, run pnpm --filter web exec void email setup --platform cloudflare once.
  • A PostgreSQL 17 or newer database reachable from Cloudflare. Its URL is the deploy's DATABASE_URL. The background jobs outbox needs 17 (transaction_timeout); the deploy refuses an older server before it migrates anything.
  • A clean checkout of the commit you want to deploy, with migrations committed (void db generate).

Choosing a Database

Any hosted PostgreSQL 17 or newer works. If you don't have one yet:

ProviderPlanNotes
PlanetScaleFrom $5/monthRecommended. Cloudflare's dashboard has a one-click setup for it
NeonFree planGood for trying the kit out
SupabaseFree planGood for trying the kit out. Use it as a database only: auth and storage are the kit's

Create the database in the region closest to most of your visitors. A Worker that runs far from its database pays for the distance on every query: CPU and Database explains how to place the Worker near it. Cloudflare's PlanetScale guide covers the same for PlanetScale. Skip that guide's Hyperdrive step: the kit's deploy creates the Hyperdrive config from DATABASE_URL.

Pick PostgreSQL 17 or newer when you create the database (18, the latest, is the best choice), and copy its connection URL: that is the deploy's DATABASE_URL. You don't need a hosted database for local development: the kit runs its own.

Create the API Token

In Cloudflare: My Profile → API Tokens → Create Token → Custom token. Scope it to your account.

PermissionNeeded for
Account → Workers Scripts: EditUploading and activating the Worker, its secrets and versions
Account → Hyperdrive: EditCreating the Hyperdrive config from DATABASE_URL
Edit access to each product Void provisionsOnly when your app uses it: Workers KV Storage, Workers R2 Storage, Queues and so on
Email Routing: Edit, Email Sending: EditOnly when your app sends email

Void's rule is "Workers Scripts: Edit, read access to bound resources, and edit access to products Void provisions". Add a permission when you add a resource. If a deploy stops on a permission error, add the permission Cloudflare names in the message and run it again.

Database Role Settings

Once, as the database owner, for the role DATABASE_URL connects as (background jobs need the first; Deploying the Outbox):

ALTER ROLE app_role SET idle_in_transaction_session_timeout = '60s';
ALTER ROLE app_role SET lock_timeout = '5s';

First Deploy From Your Machine

Workers Builds never makes the first deploy. The deploy creates resources and writes their IDs to apps/web/void.lock.json, and a build can't commit that file. The Worker must also exist before you can connect it.

pnpm --filter web exec void cloudflare login
# or: export CLOUDFLARE_API_TOKEN=… CLOUDFLARE_ACCOUNT_ID=…
pnpm --filter web exec void secret put SITE_URL # your production URL
pnpm --filter web exec void secret put PRODUCT_NAME
pnpm --filter web exec void secret put BETTER_AUTH_SECRET # openssl rand -base64 32
# migrates the database and creates its Hyperdrive config
DATABASE_URL='postgresql://…' pnpm --filter web exec vp run deploy
# once: turn off Hyperdrive's query cache (id: "hyperdrive" in apps/web/void.lock.json)
pnpm --filter web exec wrangler hyperdrive update <hyperdrive-id> --caching-disabled true
git add apps/web/void.lock.json && git commit -m "chore: production lock"

The Worker is web, from apps/web/package.json. Push the lock to main before connecting Workers Builds.

apps/web/.void/project.json ({"platform": "cloudflare"}) is committed, the only file in .void/ that is: without it, void secret and other plain void commands take Void's hosted path.

Worker Secrets

Runtime values are Worker secrets, set from your machine. Builds never set them.

Command
Set one (prompts)pnpm --filter web exec void secret put <KEY>
Set many (dotenv file)pnpm --filter web exec void secret sync <file>
List namespnpm --filter web exec void secret list
Deletepnpm --filter web exec void secret delete <KEY>
  • Keep sync files outside the repository (~/secrets/production.env), as an absolute path. Any .env.* file in apps/web stops Void.
  • A sync file holds only keys declared in env.ts. Never put DATABASE_URL in it.
  • Every key, its default and its allowed values are in Environment Variables. Keys with a default can stay unset.
  • void deploy refuses to deploy while a required key is missing remotely, so a new required key in env.ts needs its secret set before you push.

Connect Workers Builds

In Cloudflare: Workers & Pages → web → Settings → Build → Connect. Install the Cloudflare Workers & Pages GitHub App when asked, and give it access to this repository only.

SettingValue
Production branchmain
Root directoryblank (repository root)
Build commandblank
Deploy commandpnpm --filter web exec vp run deploy
Non-production branch buildsOff
  • Keep non-production branch builds off. Otherwise every branch's code builds with production's token, database URL and secrets.
  • Builds installs dependencies with pnpm from pnpm-lock.yaml, at the version in package.json's packageManager. Node defaults to 24; set the NODE_VERSION build variable to change it.

Then add build variables and secrets (Settings → Build → Variables and secrets). They exist during the build only, never at runtime:

KindNameValue
SecretCLOUDFLARE_API_TOKENThe token from Create the API Token
VariableCLOUDFLARE_ACCOUNT_IDYour account ID (Workers & Pages → Account details). Void needs it when the token can reach more than one account
SecretDATABASE_URLThe production Postgres URL. Used for migrations only
VariableCLOUDFLARE_WORKERS_SUBDOMAINYour workers.dev subdomain, e.g. my-team. Void uses it to reach the new version for the readiness check when the version has no preview URL
Secret, optionalCF_ACCESS_CLIENT_ID, CF_ACCESS_CLIENT_SECRETA Cloudflare Access service token, when Access protects the Worker

Set your own CLOUDFLARE_API_TOKEN even though Workers Builds runs inside your account: void deploy needs the permissions listed above.

Limits: a build times out after 20 minutes; 3,000 build minutes a month on Free, 6,000 on Paid.

Protect Main

Deploys start on the push and don't wait for the GitHub checks. In GitHub: Settings → Branches (or Rules) → add a rule for main:

  • Require a pull request before merging.
  • Require status checks to pass: Format, lint and types, Unit tests, Build, E2E.
  • Block direct pushes, or limit them to people you trust.

A direct push to an unprotected main deploys without the checks.

What a Deploy Does

On a push to main, Workers Builds installs dependencies and runs vp run deploy (tooling/scripts/src/deploy.mjs, which passes any extra arguments to void deploy --platform cloudflare):

  1. The kit checks that DATABASE_URL is PostgreSQL 17 or newer, and stops before anything migrates if it isn't.
  2. Void checks the required Worker secrets and schema drift, migrates the database with DATABASE_URL, uploads a version, checks /__void/ready on it, then sends it traffic. It restores the previous version if readiness fails.

The same task deploys from your machine.

Adding a Resource

Adding KV, R2, a queue or email to the app changes the lock: the deploy writes the new resource IDs to void.lock.json. Deploy that change from your machine (pnpm --filter web exec vp run deploy) and commit the lock before pushing. A build would provision the resource and deploy, but its updated lock is lost with the build.

If you did push first, deploy from your machine afterwards and check the Cloudflare dashboard for a second resource of the same kind before you commit the lock.

Rollback

pnpm --filter web exec void project status # versions
pnpm --filter web exec void project rollback [version]

Without a version, rollback shows a menu. It activates that Worker Version at 100% and restores its triggers when both versions recorded them.

Rollback never reverts migrations. The older code runs against the newer schema, so write migrations expand-then-contract:

  1. Expand: add the new column or table; keep the old one. Deploy code that works with both.
  2. Contract: drop the old one in a later deploy, once no live or rollback-target version reads it.

A deploy that fails readiness has already migrated. Fix forward with a new deploy, or with a new migration.

DATABASE_URL Rules

  • Deploy shell only. void deploy reads DATABASE_URL from its environment to create the Hyperdrive config and run migrations. Locally, prefix the deploy command; in Workers Builds it is a build secret. vp run deploy stops with deploy: set DATABASE_URL in the deploy shell when the variable is missing. Always set it explicitly, so the deploy can never pick up your local database.
  • Hyperdrive at runtime. The deployed Worker connects through the HYPERDRIVE binding, which pools connections near your database.
  • Turn on Analytics Engine. Audit events are stored in a Cloudflare Analytics Engine dataset that void.config.ts binds. On an account that never used it, the first deploy stops with code 10089: open Analytics Engine in the Cloudflare dashboard, select Enable, and deploy again. Without the binding audit events only reach the logs (Audit Log). Every deploy also binds the admin's audit reader (AUDIT_SQL). It only works deployed; locally there is no reader and no Cloudflare login (Read the Audit Log).
  • Check the live site. SITE_URL=https://your-site.com pnpm kit:doctor --prod reads /robots.txt and /api/health (Operations). The health check is only meaningful with query caching off.
  • Query caching off. Hyperdrive caches SELECT results for up to 60 seconds by default, and void deploy --platform cloudflare creates the config with it on (only Void's hosted platform turns it off). Cached reads would let a revoked session, or a member removed from an organization, keep access for up to a minute. Turn it off once after the first deploy (command above) and check it in the dashboard (Hyperdrive → your config → Caching).
  • Never a Worker secret. Void prefers a DATABASE_URL secret over Hyperdrive, so a Worker with one bypasses the pool. Check with void secret list, and remove it with pnpm --filter web exec void secret delete DATABASE_URL.
  • void db commands read apps/web/.env only, not the shell. Don't point .env at production to run migrations; let the deploy run them.

Common Pitfalls

  • Adding a resource and pushing. See Adding a Resource: deploy locally and commit the lock first.
  • Runtime secrets as build variables. Build variables never reach the Worker. Set SITE_URL and the rest with void secret put.
  • Non-production branch builds on. Branch code would build against production. Keep them off.
  • Connecting a second Worker to this repository for staging. It deploys with production's resource IDs; see Staging and Previews.
  • A gradual rollout left open in Cloudflare. Void won't flatten it. Finish or cancel it in the dashboard, then retry the build.

Next: Troubleshooting →