Create FasterCreate Faster

Cloudflare Workers

Cloudflare Workers deployment platform — stack-aware config for Hono, Next.js (OpenNext) and TanStack Start (Vite plugin).

Supported frameworks

→ Cloudflare Workers Documentation

What create-faster adds

Cloudflare Workers is a project-level deployment platform. Generation is stack-aware per app: a Hono app gets a direct Workers config, a Next.js app gets an OpenNext config, and a TanStack Start app gets the Cloudflare Vite plugin. Selecting it once with --deployment cloudflare configures every app according to its stack.

Hono apps

Hono already exports a Workers-compatible fetch handler (export default app), so no adapter is needed. dev runs Wrangler too, so the app develops in the Workers runtime with its bindings on c.env. There is no Node or Bun server: the app has no start script, no src/server.ts and no @hono/node-server, and the root start of a turborepo does not run it.

wrangler.jsonc
{
  "$schema": "node_modules/wrangler/config-schema.json",
  "name": "my-api",
  "main": "src/index.ts",
  "compatibility_date": "2026-06-12",
  "compatibility_flags": ["nodejs_compat"]
}

Scripts:

  • dev - Run the Worker locally on the Workers runtime, on the app port (3000 in a single repo, the port of the app in a turborepo; PORT overrides it, which is how portless reaches it), sharing the local state of the repo root (wrangler dev --persist-to <repo root>/.wrangler)
  • deploy - Deploy the Worker (wrangler deploy)
  • preview - Run the Worker locally with the same runtime and local state as dev (wrangler dev), on Wrangler's default port
  • cf-typegen - Generate binding types (wrangler types --env-interface CloudflareEnv cloudflare-env.d.ts). The app's postinstall runs it, so a fresh install type-checks; run it again after each change to wrangler.jsonc.

Next.js apps

Next.js apps deploy through the OpenNext Cloudflare adapter. next.config.ts calls initOpenNextCloudflareForDev() under next dev only (NODE_ENV is development), so Cloudflare bindings are available there and next build does not start a local workerd. The build emits the Worker output under .open-next/.

wrangler.jsonc
{
  "$schema": "node_modules/wrangler/config-schema.json",
  "name": "web",
  "main": ".open-next/worker.js",
  "compatibility_flags": ["nodejs_compat", "global_fetch_strictly_public"],
  "assets": {
    "directory": ".open-next/assets",
    "binding": "ASSETS"
  }
}
open-next.config.ts
import { defineCloudflareConfig } from '@opennextjs/cloudflare';

export default defineCloudflareConfig({});

Scripts:

  • build:cf - Generate binding types, then the OpenNext adapter build (wrangler types … && opennextjs-cloudflare build). opennextjs-cloudflare build runs the project's build script (next build) itself, in standalone mode, so next build is not repeated in build:cf. Types are generated first so the binding globals (e.g. Hyperdrive, D1Database) typecheck during that build.
  • preview - Local Wrangler preview of the built output (opennextjs-cloudflare preview)
  • deploy - Deploy the built output (opennextjs-cloudflare deploy)
  • cf-typegen - Generate binding types (wrangler types --env-interface CloudflareEnv cloudflare-env.d.ts). The app's postinstall runs it, so a fresh install type-checks; run it again after each change to wrangler.jsonc.

A Next.js app on Workers has no start script: next start runs Next's Node server, where getCloudflareContext() is never initialised, so every page returns a 500. Run build:cf then preview to serve the production build in workerd.

TanStack Start apps

TanStack Start runs on Workers through @cloudflare/vite-plugin, without Nitro: vite.config.ts registers the plugin in place of nitro(), and vite dev and vite preview run the app in workerd with the bindings declared in wrangler.jsonc. The Nitro start script and the .env.start file are not generated. The Vite config passes vars: { NODE_ENV } to the plugin, so the built wrangler.json sets NODE_ENV=production in vite preview and wrangler deploy while vite dev runs with development.

wrangler.jsonc
{
  "$schema": "node_modules/wrangler/config-schema.json",
  "name": "web",
  "main": "src/server.ts",
  "compatibility_date": "2026-06-12",
  "compatibility_flags": ["nodejs_compat"]
}

src/server.ts is the Worker entry: it exports Start's handler (@tanstack/react-start/server-entry). Libraries wrap it, for example the evlog module wraps fetch with withEvlog.

Scripts:

  • build - Build the client assets and the Worker (vite build)
  • preview - Serve the production build in workerd (vite preview). Check the build here before deploying: vite dev hides errors that only appear once the Worker is built, such as I/O or randomness at module level.
  • deploy - Build then deploy (vite build && wrangler deploy)
  • cf-typegen - Generate binding types (wrangler types --env-interface CloudflareEnv cloudflare-env.d.ts). The app's postinstall runs it, so a fresh install type-checks; run it again after each change to wrangler.jsonc: tsc reads cloudflare-env.d.ts for the cloudflare:workers module.

Bindings are read with import { env } from 'cloudflare:workers'. With --database d1, src/lib/server.ts builds the Drizzle db once at module scope from env.DB, which is safe for D1. With Postgres or MySQL, build a client per request with await createDb(env.HYPERDRIVE) (see below).

Postgres / MySQL via Hyperdrive

A Worker cannot open a raw TCP connection to a Postgres or MySQL server, and forbids reusing a connection across requests. When a Next.js or TanStack Start app uses --database postgres (or mysql) with --deployment cloudflare, the database is routed through a Cloudflare Hyperdrive binding (a pooling proxy), and the db package exports a per-request createDb(hyperdrive) factory instead of a module-level singleton.

wrangler.jsonc
"hyperdrive": [
  {
    "binding": "HYPERDRIVE",
    "id": "REPLACE_WITH_HYPERDRIVE_ID",
    "localConnectionString": "postgresql://postgres:password@localhost:5432/postgres-my-app"
  }
]
  • Setup: wrangler hyperdrive create <name> --connection-string="...", then paste the id into wrangler.jsonc. localConnectionString is used by local runs only (wrangler dev, vite dev, vite preview) and matches your local DATABASE_URL.
  • Migrations run on Node via drizzle-kit or the prisma CLI against DATABASE_URL — unchanged by Hyperdrive.
  • better-auth / tRPC over a Cloudflare binding database (per-request consumers) is not wired yet, so those combinations are disabled with a reason on Cloudflare (tracked in #153).

Shared behavior

The Worker name is the project name in single mode and <project>-<app> in turborepo mode, so two projects deployed to one Cloudflare account never share a Worker.

Production installs: wrangler is a devDependency, so an install that skips dev dependencies (npm ci --omit=dev, bun install --production, pnpm install --prod) must pass --ignore-scripts: the postinstall that runs wrangler types would fail without it. The generated README and agent notes say so.

Modified files:

  • .gitignore - Ignores .wrangler/ and cloudflare-env.d.ts; for Next.js apps it also ignores .open-next/ and .prod.env.

Runtime secrets

A runtime variable that META marks as secret: true on its envs entry (BETTER_AUTH_SECRET and BETTER_AUTH_URL for Better Auth, for example) is listed in the wrangler.jsonc of every Worker app that receives it, under Wrangler's secrets.required:

wrangler.jsonc
"secrets": {
  "required": ["BETTER_AUTH_SECRET", "BETTER_AUTH_URL"]
}

An app without such a variable gets no secrets field. In a turborepo each Worker lists only its own: a Next.js app with Better Auth and a Hono app without it get different files. Public values (NEXT_PUBLIC_*, VITE_*) are never secrets.

With the field present:

  • wrangler deploy fails until each secret is set. wrangler secret put <KEY> sets one on an existing Worker. A new Worker does not exist yet, so its first deploy takes them from a gitignored file (wrangler deploy --secrets-file <file>, with a file you keep out of git; for Next.js the deploy script takes -- --secrets-file .prod.env, a file the generated .gitignore lists).
  • Local runs (wrangler dev, vite preview) warn about a missing one.
  • Wrangler keeps only the listed keys in the local .dev.vars of the Worker, so every runtime variable the app reads must be listed.
  • wrangler types types each one as string in cloudflare-env.d.ts, whether or not a .env exists.

Local secrets go in .env (already gitignored), not .dev.vars: Wrangler ignores .env whenever a .dev.vars file is present, which would silently shadow it.

Next.js: .env is bundled into the Worker

build:cf bundles every .env* value, server secrets included, into the Worker (.open-next/cloudflare/next-env.mjs) as a process.env fallback, and OpenNext has no opt-out. A secret set with wrangler secret put wins at runtime, but the bundled value is used silently when the secret was never set. So:

  • Build the Worker you deploy where .env holds no real secret: in CI, or from a checkout without a .env.
  • Set production secrets with wrangler secret put, or --secrets-file on the first deploy.
  • preview serves the build as it is: the .env values are frozen when build:cf runs, so run it again after each .env change.
  • Wrangler does not load .env for this preview (OpenNext handles it), so preview warns about a missing required secret even when .env holds it. The warning is safe to ignore then.

TanStack Start: dist/server/.dev.vars

vite build writes dist/server/.dev.vars, a local copy of .env for vite preview (only the secrets.required keys when the Worker lists any). wrangler deploy does not upload it. Never ship dist other than through wrangler deploy, and rebuild after editing .env.

Production URL

Two things read the public URL of a Worker: BETTER_AUTH_URL of a project with Better Auth, a secret listed under secrets.required, and NEXT_PUBLIC_APP_URL of a Next.js app with tRPC. The first deploy needs a URL that wrangler deploy is the first to print. https://<worker name>.<subdomain>.workers.dev is known before: the worker name is the name of the wrangler.jsonc (<project>, or <project>-<app> in a turborepo) and the subdomain belongs to the Cloudflare account. Wrangler has no command that prints the subdomain; the Workers API does, with the token of the Wrangler login (wrangler auth token; WRANGLER_HIDE_BANNER=true keeps the banner out of the token). The account id is in wrangler whoami. The token goes through a pipe, so it never appears in the command line of curl, where ps would show it:

WRANGLER_HIDE_BANNER=true npx wrangler auth token | sed 's/^/Authorization: Bearer /' | curl -s -H @- https://api.cloudflare.com/client/v4/accounts/<account id>/workers/subdomain

The answer holds "subdomain": "<subdomain>" under result. Error code 10007 means the account has no workers.dev subdomain yet: register one at https://dash.cloudflare.com/<account id>/workers/onboarding. A Next.js app that reads NEXT_PUBLIC_APP_URL (the server-side tRPC client does) needs the same URL when it is built, as NEXT_PUBLIC_* values are frozen into the build: export it in the shell of the build, so .env needs no production value. The generated AGENTS.md prints these commands for the package manager and the directory of your project, and the cloudflare-fullstack-nextjs blueprint adds the whole first deploy and its first admin to docs/agents/cloudflare-deploy.md.

Known warnings

A Next.js (OpenNext) build and deploy print messages that change nothing:

  • Missing required secrets: <names> at the start of deploy, even with --secrets-file: the local Wrangler session OpenNext starts reads .dev.vars, .env and the environment, not the secrets file, and the upload is not affected.
  • The "middleware" file convention is deprecated. Please use "proxy" instead. during next build: OpenNext runs the Edge runtime only, so on Cloudflare the app keeps src/middleware.ts where it would otherwise have src/proxy.ts.
  • DeprecationWarning: Passing args to a child process with shell option true (DEP0190) at the end of deploy, from the OpenNext CLI.

Turborepo mode: wrangler.jsonc (and open-next.config.ts for Next.js apps) is placed in apps/<name>/, and the Worker is named <project>-<app>. Run the scripts from the app directory.

On this page