Cloudflare

Generate the Cloudflare setup

Run the Cloudflare generator from the repository root:

pnpm turbo gen cloudflare

The generator asks for:

• Worker name - the Cloudflare Worker name, usually your product slug
• R2 bucket name - the bucket used by OpenNext for incremental cache
• Hyperdrive config id - paste this after you create Hyperdrive in the next step
• Local database URL - used by Wrangler preview
• App URL - used by local Cloudflare preview
• Wrangler compatibility date - keep the default unless you have a reason to pin it

It creates and updates the files needed by the web app:

• apps/web/wrangler.jsonc
• apps/web/open-next.config.ts
• apps/web/scripts/cf-build.mjs
• apps/web/.dev.vars.example
• apps/web/next.config.ts
• apps/web/package.json
• apps/web/middleware.ts
• packages/db/src/server.ts
• turbo.json

It also adds scripts like cf:build, cf:preview, cf:deploy, cf:upload, and cf:typegen to the web package.

Create Hyperdrive

Cloudflare Workers run globally, while most Postgres databases live in one region. Hyperdrive keeps pooled connections inside Cloudflare's network and exposes a Worker binding called HYPERDRIVE.

Create a Hyperdrive configuration with your production database URL:

pnpm --filter web exec wrangler hyperdrive create <name> --connection-string="$DATABASE_URL"

Copy the returned id into apps/web/wrangler.jsonc:

{
  "hyperdrive": [
    {
      "binding": "HYPERDRIVE",
      "id": "<your-hyperdrive-id>",
      "localConnectionString": "postgresql://turbostarter:turbostarter@localhost:5432/core"
    }
  ]
}

Keep localConnectionString pointed at your local database. Wrangler uses it when you run cf:preview.

Create the R2 cache bucket

The generated open-next.config.ts configures OpenNext to use R2 for incremental cache. Create the bucket with the same name you entered in the generator:

pnpm --filter web exec wrangler r2 bucket create <bucket-name>

Then verify the binding in apps/web/wrangler.jsonc:

{
  "r2_buckets": [
    {
      "binding": "NEXT_INC_CACHE_R2_BUCKET",
      "bucket_name": "<bucket-name>"
    }
  ]
}

If you are not using ISR or cached server data yet, you can still keep this bucket configured. It gives your app the right production shape before you need it.

Configure environment variables

Cloudflare needs two kinds of variables:

• Build-time variables - available when cf:build runs, especially NEXT_PUBLIC_ values and anything used by static generation
• Runtime variables and secrets - available to the deployed Worker

For local preview, copy the generated example file:

cp apps/web/.dev.vars.example apps/web/.dev.vars

Keep your normal local values in .env.local and apps/web/.env.local as described in environment variables. Use .dev.vars only for values Wrangler needs during Worker preview, such as DATABASE_URL and URL.

For production, add the same variables you use for other deployments:

URL="https://example.com"
BETTER_AUTH_URL="https://example.com"
NEXT_PUBLIC_URL="https://example.com"
DATABASE_URL="postgresql://..."
BETTER_AUTH_SECRET="..."

You can set them in the Cloudflare dashboard or with Wrangler:

pnpm --filter web exec wrangler secret put DATABASE_URL
pnpm --filter web exec wrangler secret put BETTER_AUTH_SECRET

The generated wrangler.jsonc includes keep_vars: true, so deployments will not remove variables you manage in the Cloudflare dashboard.

Generate Cloudflare types

After wrangler.jsonc has a real Hyperdrive id and R2 bucket name, generate Worker binding types:

pnpm --filter web cf:typegen

This creates apps/web/cloudflare-env.d.ts. The generator also adds that file to the web app's TypeScript config.

Preview locally

Run the app in the same Workers runtime it will use in production:

pnpm --filter web cf:preview

Test the paths that depend on external services:

• sign in and sign out
• organization creation
• database reads and writes
• billing checkout and webhooks
• email sending
• file uploads, if your app uses storage

Deploy

Deploy the Worker from your local machine:

pnpm --filter web cf:deploy

This runs the custom Cloudflare build script, transforms the Next.js output with OpenNext, uploads the Worker, and deploys it to Cloudflare.

If you want to upload a version without immediately routing traffic to it, use:

pnpm --filter web cf:upload

After deployment, open the Worker URL and update your production URL, NEXT_PUBLIC_URL, BETTER_AUTH_URL, OAuth callbacks, and billing webhooks to use the final domain.

Add a custom domain

In the Cloudflare dashboard, open your Worker and add a custom domain or route for your production host.

After the domain is active:

• update URL, NEXT_PUBLIC_URL, and BETTER_AUTH_URL
• update OAuth redirect URLs in each provider
• update billing webhook URLs to /api/billing/webhook
• redeploy with pnpm --filter web cf:deploy