> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tuturuuu.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Web route families on Cloudflare

> apps/web route families built as OpenNext Workers and served behind the gateway: family manifest, pruning, build inputs, environment names and rollback.

`apps/web` stays one Next.js app on Vercel. Selected route families are also
built as their own Cloudflare Worker (`tuturuuu-web-<family>`) and served on
`tuturuuu.com` through the gateway's service bindings. Anything not owned by a
flagged family keeps going to Vercel. Gateway dispatch, header contract and
rollback are in [Gateway Worker](https://docs.tuturuuu.com/build/devops/gateway-worker.md#web-route-families).

## Why one Worker per family

OpenNext named `functions` are not a multi-Worker mechanism: the Cloudflare
entrypoint dispatches only to the default server function. Each family is an
independent build of a route-pruned copy of the app, which keeps every Worker
under the 10 MiB gzip upload limit (CI budget 9.5 MiB).

## Files

| File | Purpose |
| - | - |
| `apps/web/cloudflare/opennext/families.json` | Family table: `id`, `worker`, `kind` (`api` or `pages`), `enabled`, `held` (why a declared family is not enabled), `localized` (paths match after the `[locale]` segment), `assetPrefix`, `wrangler`, `exact`, `prefix`, `exclude`, plus the global `deny` list. Enabled families must equal `webFamilies` in `apps/gateway/src/manifest.json`, in order; every app route entry belongs to at most one declared family (test-enforced). |
| `apps/web/cloudflare/opennext/prune.ts` | Deletes every app route entry (page, route, metadata route) the family does not own, except `api/build-info` (the build probe; the gateway routes it only to the family that owns it). Refuses held families. Dry run by default; `--apply` refuses unless `apps/web/.opennext-disposable-checkout` exists, and writes `prune-receipt.json`. |
| `scripts/ci/web-opennext-size.mjs` | Whole-upload gzip size gate over the `wrangler deploy --dry-run --outdir` output; fails above 9.5 MiB. |
| `scripts/ci/web-opennext-smoke.mjs` | Serves the built Worker locally with the production Host, no provider auth and all outbound requests refused; checks `/api/build-info` reports the commit, the emitted `deploymentId` is `web-<family>-<sha12>`, and the family probe paths answer as expected. |
| `scripts/ci/gateway-deploy-config.mjs` | Gateway deploy config: committed `apps/gateway/wrangler.jsonc` merged with the live Worker's variables and service bindings, plus the origins and flagged family bindings. |
| `apps/web/cloudflare/opennext/next-family-config.ts` | With `WEB_OPENNEXT_FAMILY` set: `deploymentId: web-<family>-<sha12>` (cross-family navigation becomes a hard navigation), `generateBuildId` = the full commit, `assetPrefix` for page families. Unset: no change to the Vercel build. |
| `apps/web/open-next.config.ts` | `defineCloudflareConfig({})`: no incremental cache, tag cache or queue for API families. |
| `apps/web/cloudflare/opennext/wrangler.<family>.jsonc` | Route-free Worker config (`workers_dev`/`preview_urls` false, `nodejs_compat`), secret names only. |
| `apps/web/cloudflare/opennext/<family>.env.json` | Every environment variable name the family reads, and the names that must stay unset. |

## Building a family (CI only)

The build runs in a disposable CI checkout at the exact commit, never on a
workstation:

```bash theme={null}
bun install --frozen-lockfile
bun x --no-install turbo run build --filter='@tuturuuu/web^...' --concurrency=2
printf 'disposable checkout for an OpenNext family build\n' > apps/web/.opennext-disposable-checkout
bun run --cwd apps/web opennext:prune api-identity --apply
WEB_OPENNEXT_FAMILY=api-identity WEB_OPENNEXT_SHA=<sha> bun run --cwd apps/web build:opennext
```

`build:opennext` runs `opennextjs-cloudflare build` with
`cloudflare/opennext/wrangler.$WEB_OPENNEXT_FAMILY.jsonc`.

Toolchain: `@opennextjs/cloudflare@1.20.17` (an `apps/web` dev dependency)
with `patches/@opennextjs%2Fcloudflare@1.20.17.patch`, which runs Next's staged
render tasks in sequence on workerd when `cacheComponents` is on. Parley and
Lettin keep their patched 1.20.6.

## Deploying

`.github/workflows/web-opennext.yaml` runs on every `production` push that
touches `apps/web`, `apps/gateway`, `packages` or the lockfile, and on dispatch
from `production` (one `family`, and whether to deploy the gateway). Both
deploy jobs run only on `refs/heads/production`, in the `colab-production`
environment that holds the account deployment token, so the production
promotion is the human gate. The token is the environment secret
`WEB_OPENNEXT_CLOUDFLARE_API_TOKEN`, used only by this workflow, with Workers
Scripts edit on the Tuturuuu account; it creates the family Workers and
reads and versions `tuturuuu-gateway`:

1. **family** (one job per enabled family): exact-commit checkout, workspace
   package build, prune, family build, size gate, local smoke, then
   `wrangler deploy` of the route-free Worker with the commit in the version
   message. Public configuration comes from the `PRODUCTION_SUPABASE_URL` and
   `PRODUCTION_SUPABASE_PUBLISHABLE_KEY` repository variables, and
   `ROOT_WORKSPACE_ID` is the root workspace constant; the job passes no Worker
   secret.
2. **gateway**: captures the live gateway settings, checks that every family in
   the `GATEWAY_WEB_FAMILIES` variable has its Worker and every secret name its
   wrangler config requires, writes the deploy config, then
   `wrangler versions upload` and `versions deploy` at 100%. `WEB_ORIGIN` comes
   from the `GATEWAY_WEB_ORIGIN` variable and `MARKETING_ORIGIN` is
   `https://marketing.tuturuuu.com`. The deploy config requires both origins to
   match their live plain-text bindings exactly. It refuses any acceptance
   hostname or Vercel protection bypass setting in the committed config, live
   bindings, or deploy environment. The pre-write log shows family IDs and the
   presence of these settings without exposing origin or bypass values.

Turning a family on: set its Worker secrets (names in `<family>.env.json`),
mark it `"activated": true` in `families.json` in a reviewed commit, add its id
to `GATEWAY_WEB_FAMILIES`, and rerun the gateway job. The gateway deploy refuses
any flagged family that the committed table does not mark activated.

## public-docs

Owns `/changelog/**`, `/docs`, `/ui/**` and `/visualizations/**`, with or
without a locale prefix (`/docs` and `/ui/**` answer the same redirects as
Vercel). Client assets load from `/_f/public-docs/_next/**`, which the gateway
strips before the family sees it. The family requires no secrets: the changelog
reads published entries with the publishable-key client. Without an Upstash
store the proxy abuse guard logs `abuse-guard-store-missing` once per isolate.
Server actions use a per-build key, so an action posted from a page built by
another deployment fails closed.

## api-identity

Owns `/api/build-info`, `/api/health`, `/api/auth/me`, `/api/v1/workspaces`
(the collection, `limits` and `personal`), `/api/workspaces/invitations`,
`/api/v1/notifications/**`, `/api/v1/user/**` and `/api/v1/users/**`, except:

* `/api/v1/users/chatgpt` (Node file store),
* `/api/v1/users/me/{avatar,banner}/upload` (sharp image transform),
* `/api/v1/users/me/playgrounds/**` (devbox preview proxy),
* `/api/v1/users/me/{password,delete,email,identities}/**` (session-mutating;
  they move with the auth family).

The family defines no server actions, so it builds with a random per-build
action key in ordinary CI. `PLATFORM_LOG_DRAIN_DATABASE_URL` stays unset on the
Worker: `lib/infrastructure/log-drain.ts` would otherwise open a Postgres TCP
connection. `VERCEL`/`VERCEL_ENV` stay unset because they select Vercel
client-IP trust; the Worker sets `TRUSTED_PROXY=cloudflare` and
`TUTURUUU_DEPLOY_ENV=production`. The complete name list is in
`apps/web/cloudflare/opennext/api-identity.env.json`.

## Rollback

Remove the family id from the `GATEWAY_WEB_FAMILIES` repository variable and
rerun the gateway job, or roll the gateway back to the previous version printed
by that job (`wrangler rollback <version-id> --name tuturuuu-gateway`);
`GATEWAY_MODE=passthrough` disables every family. The family Worker
has no routes, so leaving it deployed serves nothing.

Regression coverage: `apps/web/cloudflare/opennext/families.test.ts` (route
ownership, gateway parity, disposable-checkout guard, Next config gating) and
`apps/gateway/src/web-family.test.ts` (dispatch, deny list, header contract).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.