Skip to content

Commit 2b5c848

Browse files
irvinebroqueharshil1712
authored andcommitted
Clarify node.js vs edge runtime in Next.js <> Pages docs (#17196)
Provide more guidance for which adapter to use when, and what will/won't work.
1 parent 9b3e651 commit 2b5c848

File tree

1 file changed

+15
-3
lines changed

1 file changed

+15
-3
lines changed

src/content/docs/pages/framework-guides/nextjs/ssr/supported-features.mdx

Lines changed: 15 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -13,18 +13,30 @@ import { Details } from "~/components"
1313

1414
`@cloudflare/next-on-pages` supports all minor and patch version of Next.js 13 and 14. We regularly run manual and automated tests to ensure compatibility.
1515

16-
### Node.js
16+
### Node.js API support
1717

18-
Next.js has [two "runtimes"](https://nextjs.org/docs/app/building-your-application/rendering/edge-and-nodejs-runtimes) — "Edge" and "Node.js". When you run your Next.js app on Cloudflare, you [can use available Node.js APIs](/workers/runtime-apis/nodejs/) — but you currently can only use Next.js' "Edge" runtime.
18+
Next.js has [two "runtimes"](https://nextjs.org/docs/app/building-your-application/rendering/edge-and-nodejs-runtimes) — "Edge" and "Node.js".
1919

20-
The Workers runtime [supports a broad set of Node.js APIs](/workers/runtime-apis/nodejs/) — but [the Next.js Edge Runtime code intentionally constrains this](https://github.com/vercel/next.js/blob/canary/packages/next/src/build/webpack/plugins/middleware-plugin.ts#L820). As a result, only the following Node.js APIs work in a Next.js app:
20+
The `@cloudflare/next-on-pages` adapter supports only the edge "runtime".
21+
22+
The [`@opennextjs/cloudflare` adapter](https://opennext.js.org/cloudflare), which lets you build and deploy Next.js apps to [Cloudflare Workers](/workers/), supports the Node.js "runtime" from Next.js. When you use it, you can use the [full set of Node.js APIs](/workers/runtime-apis/nodejs/) that Cloudflare Workers provide.
23+
24+
`@opennextjs/cloudflare` is pre 1.0, and still in active development. As it approaches 1.0, it will become the clearly better choice for most Next.js apps, since Next.js has been engineered to only support its Node.js "runtime" for many newly introduced features.
25+
26+
Refer to the [OpenNext docs](https://opennext.js.org/cloudflare) and the [Workers vs. Pages compatibility matrix](/workers/static-assets/compatibility-matrix/) for more information to help you decide which to use.
27+
28+
#### Supported Node.js APIs when using `@cloudflare/next-on-pages`
29+
30+
When you use `@cloudflare/next-on-pages`, your Next.js app must use the "edge" runtime from Next.js. The Workers runtime [supports a broad set of Node.js APIs](/workers/runtime-apis/nodejs/) — but [the Next.js Edge Runtime code intentionally constrains this](https://github.com/vercel/next.js/blob/canary/packages/next/src/build/webpack/plugins/middleware-plugin.ts#L820). As a result, only the following Node.js APIs will work in your Next.js app:
2131

2232
* `buffer`
2333
* `events`
2434
* `assert`
2535
* `util`
2636
* `async_hooks`
2737

38+
If you need to use other APIs from Node.js, you should use [`@opennextjs/cloudflare`](https://opennext.js.org/cloudflare) instead.
39+
2840
## Supported Features
2941

3042
### Routers

0 commit comments

Comments
 (0)