The best way to control Claude Code, Codex and more from any computer or phone
| 1 | --- |
| 2 | title: Next.js |
| 3 | description: Deploy a Next.js app to Cloudflare Workers with Cloudflare.Website.Nextjs — the OpenNext pipeline, writable ISR, and wrangler-free local dev. |
| 4 | sidebar: |
| 5 | order: 9.5 |
| 6 | --- |
| 7 | |
| 8 | import PackageManagers from "../../../../components/PackageManagers.astro"; |
| 9 | |
| 10 | export const devDeps = "@alchemy.run/frontend-frameworks @opennextjs/cloudflare"; |
| 11 | |
| 12 | `Cloudflare.Website.Nextjs` deploys a [Next.js](https://nextjs.org) |
| 13 | app as a Cloudflare Worker. It runs `next build` through the OpenNext |
| 14 | pipeline (`@opennextjs/cloudflare`), bundles the resulting server |
| 15 | into a self-contained Worker, and deploys client assets plus |
| 16 | prerendered pages as Worker static assets. No OpenNext config or |
| 17 | Wrangler file is required. |
| 18 | |
| 19 | App Router and Pages Router both work — server components, API |
| 20 | routes, middleware, server actions, dynamic segments, streaming SSR, |
| 21 | and `getServerSideProps` pages all run in the Worker. |
| 22 | |
| 23 | ## Install |
| 24 | |
| 25 | The build integration is not bundled with alchemy. Install |
| 26 | `@alchemy.run/frontend-frameworks` and its OpenNext peer; the resource |
| 27 | loads the package's `/nextjs` export from your project at deploy time. |
| 28 | They are only used at build time, so dev dependencies are enough: |
| 29 | |
| 30 | <PackageManagers dev={devDeps} /> |
| 31 | |
| 32 | Alchemy leaves native `next.config.*` and Tailwind configuration unchanged. |
| 33 | No Alchemy plugin is required. OpenNext configuration is optional; without it, |
| 34 | the default cache serves prerendered pages from static assets. Use |
| 35 | [Writable ISR](#writable-isr) for revalidation. |
| 36 | |
| 37 | ## Declare the Website |
| 38 | |
| 39 | Declare the site as a module-level const (rather than inline in the |
| 40 | Stack) and derive the typed shape of its bindings from it: |
| 41 | |
| 42 | ```typescript |
| 43 | // alchemy.run.ts |
| 44 | import * as Cloudflare from "@alchemy.run/cloudflare"; |
| 45 | |
| 46 | export const Website = Cloudflare.Website.Nextjs("Website"); |
| 47 | |
| 48 | export type WebsiteEnv = Cloudflare.InferEnv<typeof Website>; |
| 49 | ``` |
| 50 | |
| 51 | `WebsiteEnv` is the typed shape of the Worker's bindings, derived |
| 52 | from the class — you'll import it into your Next.js code in |
| 53 | [Read bindings in server code](#read-bindings-in-server-code). |
| 54 | |
| 55 | ## Optional native OpenNext configuration |
| 56 | |
| 57 | The resource declaration is the same in both cases: |
| 58 | |
| 59 | ```typescript |
| 60 | export const Website = Cloudflare.Website.Nextjs("Website"); |
| 61 | ``` |
| 62 | |
| 63 | - **Without `open-next.config.ts`:** Alchemy generates a temporary config with |
| 64 | read-only static-assets caching, or matching KV adapters when `isr` is set. |
| 65 | You do not need to create a config file. |
| 66 | - **With `open-next.config.ts`:** Alchemy automatically loads the file from |
| 67 | `rootDir` (the working directory by default) through OpenNext's native compiler. |
| 68 | It never rewrites the file. Imports and callbacks are preserved, and you can |
| 69 | use the full native `OpenNextConfig` shape within Cloudflare's adapter |
| 70 | constraints. This does not make AWS-specific runtime features available on Workers. |
| 71 | |
| 72 | For example, an optional native config retaining read-only static-assets caching: |
| 73 | |
| 74 | ```typescript |
| 75 | // open-next.config.ts |
| 76 | import { defineCloudflareConfig, type OpenNextConfig } from "@opennextjs/cloudflare"; |
| 77 | import staticAssetsIncrementalCache from "@opennextjs/cloudflare/overrides/incremental-cache/static-assets-incremental-cache"; |
| 78 | |
| 79 | export default { |
| 80 | ...defineCloudflareConfig({ incrementalCache: staticAssetsIncrementalCache }), |
| 81 | buildCommand: "pnpm exec next build", |
| 82 | } satisfies OpenNextConfig; |
| 83 | ``` |
| 84 | |
| 85 | ## Add it to the Stack |
| 86 | |
| 87 | Yield the class from your Stack and return its URL: |
| 88 | |
| 89 | ```typescript |
| 90 | // alchemy.run.ts |
| 91 | import * as Alchemy from "alchemy"; |
| 92 | import * as Effect from "effect/Effect"; |
| 93 | |
| 94 | export default Alchemy.Stack( |
| 95 | "MyNextjsSite", |
| 96 | { |
| 97 | providers: Cloudflare.providers(), |
| 98 | state: Cloudflare.state(), |
| 99 | }, |
| 100 | Effect.gen(function* () { |
| 101 | const site = yield* Website; |
| 102 | return { url: site.url }; |
| 103 | }), |
| 104 | ); |
| 105 | ``` |
| 106 | |
| 107 | The OpenNext server runs under Node compatibility, so the |
| 108 | `nodejs_compat` compatibility flag is added automatically. |
| 109 | |
| 110 | See |
| 111 | [examples/cloudflare-website-nextjs](https://github.com/alchemy-run/alchemy/tree/main/examples/cloudflare-website-nextjs) |
| 112 | for the checked-in example. |
| 113 | |
| 114 | ## Add bindings |
| 115 | |
| 116 | The resource returns a plain `Worker`, so `env` accepts the full |
| 117 | binding vocabulary — KV namespaces, R2 buckets, Durable Objects, |
| 118 | secrets: |
| 119 | |
| 120 | ```diff lang="typescript" |
| 121 | // alchemy.run.ts |
| 122 | +import * as Config from "effect/Config"; |
| 123 | |
| 124 | +export const Uploads = Cloudflare.R2.Bucket("Uploads"); |
| 125 | |
| 126 | export const Website = Cloudflare.Website.Nextjs("Website", { |
| 127 | + env: { |
| 128 | + UPLOADS: Uploads, |
| 129 | + API_KEY: Config.Redacted("API_KEY"), |
| 130 | + }, |
| 131 | }); |
| 132 | ``` |
| 133 | |
| 134 | `Uploads` is a description, not a deploy — Alchemy provisions the |
| 135 | real bucket because the Website binds it. `Config.Redacted` reads |
| 136 | `API_KEY` from your environment at deploy time and binds it as a |
| 137 | Worker secret — see [Secrets & env](/cloudflare/security/secrets-env). |
| 138 | |
| 139 | ## Read bindings in server code |
| 140 | |
| 141 | Route handlers, server components, and server actions read bindings |
| 142 | through OpenNext's `getCloudflareContext()`. Its `env` is typed by |
| 143 | the global `CloudflareEnv` interface — extend it once with the |
| 144 | inferred env type: |
| 145 | |
| 146 | ```typescript |
| 147 | // cloudflare-env.d.ts |
| 148 | import type { WebsiteEnv } from "./alchemy.run.ts"; |
| 149 | |
| 150 | declare global { |
| 151 | interface CloudflareEnv extends WebsiteEnv {} |
| 152 | } |
| 153 | |
| 154 | export {}; |
| 155 | ``` |
| 156 | |
| 157 | Every server entry point now gets fully typed bindings: |
| 158 | |
| 159 | ```typescript |
| 160 | // app/api/upload/route.ts |
| 161 | import { getCloudflareContext } from "@opennextjs/cloudflare"; |
| 162 | |
| 163 | export async function PUT(request: Request) { |
| 164 | const { env } = getCloudflareContext(); |
| 165 | await env.UPLOADS.put("hello.txt", await request.text()); |
| 166 | return Response.json({ ok: true }); |
| 167 | } |
| 168 | ``` |
| 169 | |
| 170 | `env.UPLOADS` is typed as an R2 bucket and `env.API_KEY` as a |
| 171 | string — renaming a binding in `alchemy.run.ts` is a type error in |
| 172 | your routes. |
| 173 | |
| 174 | ## Writable ISR |
| 175 | |
| 176 | Switch the incremental cache to KV and revalidation actually writes: |
| 177 | `revalidatePath` / `revalidateTag` purge entries, and time-based |
| 178 | `revalidate` windows regenerate pages in the background through a |
| 179 | Durable Object queue hosted on the same Worker. |
| 180 | |
| 181 | |
| 182 | ```typescript |
| 183 | // alchemy.run.ts |
| 184 | export const IncCache = Cloudflare.KV.Namespace("NextIncCache"); |
| 185 | export const TagCache = Cloudflare.KV.Namespace("NextTagCache"); |
| 186 | |
| 187 | export const Website = Cloudflare.Website.Nextjs("Website", { |
| 188 | isr: { incrementalCache: IncCache, tagCache: TagCache }, |
| 189 | }); |
| 190 | ``` |
| 191 | |
| 192 | Alchemy binds the cache namespaces, revalidation queue, and Worker |
| 193 | self-reference. Without a native config, it also selects the matching adapters. |
| 194 | If you supply `open-next.config.ts`, select `kv-incremental-cache`, |
| 195 | `kv-next-tag-cache`, and `do-queue` there to match these bindings: `isr` does |
| 196 | not override the file's adapter choices. The static-assets example above is |
| 197 | read-only, not a writable-ISR configuration. |
| 198 | |
| 199 | The KV cache fills on demand; build-time cache entries are not uploaded to KV. |
| 200 | Pages using writable ISR must be able to regenerate with runtime credentials |
| 201 | and data sources. |
| 202 | |
| 203 | ## Build options |
| 204 | |
| 205 | ```typescript |
| 206 | export const Website = Cloudflare.Website.Nextjs("Website", { |
| 207 | openNext: { buildCommand: "pnpm exec next build", minify: true }, |
| 208 | }); |
| 209 | ``` |
| 210 | |
| 211 | An explicit `openNext.buildCommand` overrides the native config's |
| 212 | `buildCommand`. If neither sets a command, the default is `npx next build`. |
| 213 | `openNext.minify` and `openNext.debug` remain resource-level build controls. |
| 214 | |
| 215 | ## Rebuild scope |
| 216 | |
| 217 | Unchanged inputs skip the OpenNext build. By default, project files outside |
| 218 | build outputs and `node_modules`, plus the nearest package-manager lockfile, |
| 219 | participate in the content hash. |
| 220 | |
| 221 | The native `open-next.config.ts` itself is always hashed, even when `memo` |
| 222 | narrows the scope. When narrowing `memo.include`, include any helpers imported |
| 223 | by the config too, for example `config/**`: |
| 224 | |
| 225 | ```typescript |
| 226 | export const Website = Cloudflare.Website.Nextjs("Website", { |
| 227 | memo: { |
| 228 | include: ["app/**", "public/**", "package.json", "next.config.mjs", "config/**"], |
| 229 | }, |
| 230 | }); |
| 231 | ``` |
| 232 | |
| 233 | ## Local dev |
| 234 | |
| 235 | ```sh |
| 236 | bun alchemy dev |
| 237 | ``` |
| 238 | |
| 239 | `alchemy dev` defaults to **preview parity**: the OpenNext worker is |
| 240 | built and served under workerd locally, with the Worker's bindings |
| 241 | emulated — the same runtime behavior, asset routing, and ISR/cache |
| 242 | semantics as production. |
| 243 | |
| 244 | For an edit-refresh loop, switch to the real `next dev` (Turbopack |
| 245 | HMR): |
| 246 | |
| 247 | ```typescript |
| 248 | export const Website = Cloudflare.Website.Nextjs("Website", { |
| 249 | dev: { mode: "hmr" }, |
| 250 | }); |
| 251 | ``` |
| 252 | |
| 253 | In hmr mode your app code runs in Node with the Worker's bindings |
| 254 | proxied onto `getCloudflareContext()` — no |
| 255 | `initOpenNextCloudflareForDev()` call needed. Cloudflare-specific |
| 256 | runtime behavior (workerd APIs, ISR semantics) still needs preview |
| 257 | mode. |
| 258 | |
| 259 | ## Limitations |
| 260 | |
| 261 | These come from upstream `@opennextjs/cloudflare`: |
| 262 | |
| 263 | - **Edge-runtime routes and pages** (`export const runtime = "edge"`) |
| 264 | are unsupported and would fail at runtime, so the build fails early |
| 265 | with the offending route list. Remove the directive — the node |
| 266 | runtime runs on Workers. Middleware is fully supported. |
| 267 | - **`next/image` optimization** requires a zone with Cloudflare |
| 268 | Images. On `workers.dev`, pass `unoptimized` and images serve as |
| 269 | raw static assets. |
| 270 | - **Partial Prerendering / `"use cache"`** and Pages-Router `i18n` |
| 271 | config are out of scope for now. App Router i18n via middleware |
| 272 | works. |