/cloudflare-nextjs

name: cloudflare-nextjs
description: "Deploy Next.js to Cloudflare Workers via the OpenNext adapter (@opennextjs/cloudflare). Use for SSR/ISR/SSG/App or Pages Router, getCloudflareContext, bindings (D1/R2/KV/AI/Hyperdrive), caching tiers, skew protection, multi-worker, custom worker, env vars, or worker size/runtime/keep_names/FinalizationRegistry/connection-scoping errors."
license: MIT
metadata:
  version: 2.0.0
  last_verified: 2026-08-05
  package_versions:
    "@opennextjs/cloudflare": "^1.18.1"
    "next": "^14.2.0 || ^15.0.0 || ^16.0.0"
    "wrangler": "^4.81.0"
  compatibility_requirements:
    compatibility_date: "2025-05-05"
    compatibility_flags: ["nodejs_compat", "global_fetch_strictly_public"]
    min_wrangler: "3.99.0"
  token_savings: "~60%"
  errors_prevented: 18+
  sources:
    overview: "https://opennext.js.org/cloudflare"
    get_started: "https://opennext.js.org/cloudflare/get-started"
    cli: "https://opennext.js.org/cloudflare/cli"
    bindings: "https://opennext.js.org/cloudflare/bindings"
    caching: "https://opennext.js.org/cloudflare/caching"
    howto_stripe: "https://opennext.js.org/cloudflare/howtos/stripeAPI"
    howto_db: "https://opennext.js.org/cloudflare/howtos/db"
    howto_dev_deploy: "https://opennext.js.org/cloudflare/howtos/dev-deploy"
    howto_env_vars: "https://opennext.js.org/cloudflare/howtos/env-vars"
    howto_image: "https://opennext.js.org/cloudflare/howtos/image"
    howto_custom_worker: "https://opennext.js.org/cloudflare/howtos/custom-worker"
    howto_keep_names: "https://opennext.js.org/cloudflare/howtos/keep_names"
    howto_workerd: "https://opennext.js.org/cloudflare/howtos/workerd"
    howto_skew: "https://opennext.js.org/cloudflare/howtos/skew"
    howto_assets: "https://opennext.js.org/cloudflare/howtos/assets"
    howto_multi_worker: "https://opennext.js.org/cloudflare/howtos/multi-worker"
    performance: "https://opennext.js.org/cloudflare/perf"
    known_issues: "https://opennext.js.org/cloudflare/known-issues"
    troubleshooting: "https://opennext.js.org/cloudflare/troubleshooting"
    migration_06_to_1: "https://opennext.js.org/cloudflare/migrate-from-0.6-to-1.0.0-beta"
    open_issues: "https://github.com/opennextjs/opennextjs-cloudflare/issues"
  keywords:
    - OpenNext Cloudflare
    - "@opennextjs/cloudflare"
    - opennextjs-cloudflare cli
    - Next.js on Workers
    - Next.js App Router Cloudflare
    - Next.js Pages Router Cloudflare
    - Next.js SSR Cloudflare
    - Next.js ISR Workers
    - server components cloudflare
    - server actions workers
    - Next.js middleware workers
    - getCloudflareContext
    - nodejs_compat
    - global_fetch_strictly_public
    - workerd runtime
    - worker size limit
    - next.js runtime compatibility
    - database connection scoping
    - R2 incremental cache
    - Durable Objects queue
    - skew protection
    - multi-worker
    - custom worker
    - keep_names
    - FinalizationRegistry

OpenNext Cloudflare Adapter — Next.js on Workers

Deploy Next.js applications to **Cloudflare Workers** using the OpenNext adapter (`@opennextjs/cloudflare`). The adapter takes a standard Next.js build, runs `package.json` build script, then transforms the output to run on the Workers runtime using the Node.js compatibility layer (`nodejs_compat`) — **not** the Edge runtime.

Critical Requirements (get these wrong and the build/runtime fails)

| Requirement | Value | Why | |---|---|---| | Runtime | **Node.js** (default). Remove every `export const runtime = "edge";` | Edge runtime is unsupported; OpenNext uses `nodejs_compat`. | | `compatibility_flags` | `["nodejs_compat", "global_fetch_strictly_public"]` | Node APIs + allow `fetch()` in app code. | | `compatibility_date` | **≥ `2024-09-23`**; **≥ `2025-05-05`** recommended (FinalizationRegistry) | Older dates break `FinalizationRegistry`, DOs, and more. | | Wrangler | **≥ `3.99.0`** to deploy; **≥ `4.13.0`** for `keep_names`; **≥ `4.36.0`** for stable remote bindings | Feature gates in the docs. | | Next.js | v16 all minors/patches supported; latest minors of v14 and v15; **v14 dropped Q1 2026** | Stated on the overview page. | | Worker size (gzip) | **3 MiB Free / 10 MiB Paid** (compressed only) | Hard Cloudflare limits. |

**Windows:** not fully guaranteed (Next.js tooling issues). Use WSL, a Linux VM, or Linux/macOS CI. See known issue #1305.

Disambiguation: this skill vs `nextjs`

• **`nextjs` skill** → framework/App Router/Server Components/Cache Components patterns, **any platform** (Vercel, self-hosted, ...). Use for `async params`, `proxy.ts` migration, `"use cache"`.
• **THIS skill (`cloudflare-nextjs`)** → deploying Next.js to **Workers** via the OpenNext adapter: `wrangler.jsonc`, `open-next.config.ts`, `getCloudflareContext`, caching tiers, bindings, skew protection, multi-worker, the Workers-specific errors.

> **proxy.ts caveat (Next 16):** Next 16 renamed `middleware.ts` → `proxy.ts`, but `@opennextjs/cloudflare` does **not** recognize `proxy.ts` yet (issue #1277) — on Cloudflare, keep using `middleware.ts`. This is the one place the `nextjs` skill's guidance does NOT apply here.

Quick Start

New project (recommended)

npm create cloudflare@latest -- my-next-app --framework=next --platform=workers

C3 scaffolds a Next.js app, installs `@opennextjs/cloudflare`, creates `wrangler.jsonc` + `open-next.config.ts` + `.dev.vars`, wires `package.json` scripts, and (if R2 is enabled) creates an R2 bucket for caching.

Existing Next.js project (one command)

npx @opennextjs/cloudflare migrate

`migrate` automates: install adapter + wrangler, create `wrangler.jsonc`/`open-next.config.ts`/`.dev.vars`, update scripts, add `public/_headers`, add `.open-next` to `.gitignore`, wire `initOpenNextCloudflareForDev()` into `next.config.ts`, and create+configure an R2 cache bucket (only if R2 is enabled on the account).

<details><summary>Manual install (if you prefer not to run mig