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.devsubdomain (Workers & Pages → your subdomain, for examplemy-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, runpnpm --filter web exec void email setup --platform cloudflareonce. - 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:
| Provider | Plan | Notes |
|---|---|---|
| PlanetScale | From $5/month | Recommended. Cloudflare's dashboard has a one-click setup for it |
| Neon | Free plan | Good for trying the kit out |
| Supabase | Free plan | Good 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.
| Permission | Needed for |
|---|---|
| Account → Workers Scripts: Edit | Uploading and activating the Worker, its secrets and versions |
| Account → Hyperdrive: Edit | Creating the Hyperdrive config from DATABASE_URL |
| Edit access to each product Void provisions | Only when your app uses it: Workers KV Storage, Workers R2 Storage, Queues and so on |
| Email Routing: Edit, Email Sending: Edit | Only 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 URLpnpm --filter web exec void secret put PRODUCT_NAMEpnpm --filter web exec void secret put BETTER_AUTH_SECRET # openssl rand -base64 32# migrates the database and creates its Hyperdrive configDATABASE_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 truegit 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 names | pnpm --filter web exec void secret list |
| Delete | pnpm --filter web exec void secret delete <KEY> |
- Keep sync files outside the repository (
~/secrets/production.env), as an absolute path. Any.env.*file inapps/webstops Void. - A sync file holds only keys declared in
env.ts. Never putDATABASE_URLin it. - Every key, its default and its allowed values are in Environment Variables. Keys with a default can stay unset.
void deployrefuses to deploy while a required key is missing remotely, so a new required key inenv.tsneeds 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.
| Setting | Value |
|---|---|
| Production branch | main |
| Root directory | blank (repository root) |
| Build command | blank |
| Deploy command | pnpm --filter web exec vp run deploy |
| Non-production branch builds | Off |
- 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 inpackage.json'spackageManager. Node defaults to 24; set theNODE_VERSIONbuild variable to change it.
Then add build variables and secrets (Settings → Build → Variables and secrets). They exist during the build only, never at runtime:
| Kind | Name | Value |
|---|---|---|
| Secret | CLOUDFLARE_API_TOKEN | The token from Create the API Token |
| Variable | CLOUDFLARE_ACCOUNT_ID | Your account ID (Workers & Pages → Account details). Void needs it when the token can reach more than one account |
| Secret | DATABASE_URL | The production Postgres URL. Used for migrations only |
| Variable | CLOUDFLARE_WORKERS_SUBDOMAIN | Your 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, optional | CF_ACCESS_CLIENT_ID, CF_ACCESS_CLIENT_SECRET | A 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):
- The kit checks that
DATABASE_URLis PostgreSQL 17 or newer, and stops before anything migrates if it isn't. - Void checks the required Worker secrets and schema drift, migrates the database with
DATABASE_URL, uploads a version, checks/__void/readyon 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 # versionspnpm --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:
- Expand: add the new column or table; keep the old one. Deploy code that works with both.
- 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 deployreadsDATABASE_URLfrom 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 deploystops withdeploy: set DATABASE_URL in the deploy shellwhen 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
HYPERDRIVEbinding, which pools connections near your database. - Turn on Analytics Engine. Audit events are stored in a Cloudflare Analytics Engine dataset that
void.config.tsbinds. 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 --prodreads/robots.txtand/api/health(Operations). The health check is only meaningful with query caching off. - Query caching off. Hyperdrive caches
SELECTresults for up to 60 seconds by default, andvoid deploy --platform cloudflarecreates 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_URLsecret over Hyperdrive, so a Worker with one bypasses the pool. Check withvoid secret list, and remove it withpnpm --filter web exec void secret delete DATABASE_URL. void dbcommands readapps/web/.envonly, not the shell. Don't point.envat 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_URLand the rest withvoid 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 →