The best way to control Claude Code, Codex and more from any computer or phone

main
mdx 272 lines 8.93 KB
Raw
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.