From 205c6f55b159173b4f61730ee9ee2de4d8d7dc3d Mon Sep 17 00:00:00 2001 From: Victor Berchet Date: Fri, 2 May 2025 16:28:48 +0200 Subject: [PATCH 1/5] docs(cloudflare): workerd build condition --- pages/cloudflare/howtos/_meta.json | 3 +- pages/cloudflare/howtos/workerd.mdx | 46 +++++++++++++++++++++++++++++ 2 files changed, 48 insertions(+), 1 deletion(-) create mode 100644 pages/cloudflare/howtos/workerd.mdx diff --git a/pages/cloudflare/howtos/_meta.json b/pages/cloudflare/howtos/_meta.json index 45e3c9d..c8fe30e 100644 --- a/pages/cloudflare/howtos/_meta.json +++ b/pages/cloudflare/howtos/_meta.json @@ -5,5 +5,6 @@ "env-vars": "Environment Variables", "image": "Image Optimization", "custom-worker": "Custom Worker", - "keep_names": "__name issues" + "keep_names": "__name issues", + "workerd": "workerd specific packages" } diff --git a/pages/cloudflare/howtos/workerd.mdx b/pages/cloudflare/howtos/workerd.mdx new file mode 100644 index 0000000..47d2a5c --- /dev/null +++ b/pages/cloudflare/howtos/workerd.mdx @@ -0,0 +1,46 @@ +## `workerd` specific code + +### Configuration + +[`workerd`](https://github.com/cloudflare/workerd) is the runtime cloudflare uses to run Workers code. + +While the [`nodejs_compat`](https://developers.cloudflare.com/workers/configuration/compatibility-flags/#nodejs-compatibility-flag) flag makes `workerd` mostly compatible with Node.js, +there are still minor differences. Some packages publish code for different runtimes to account for those differences. For example, `postgres` has [conditional exports](https://nodejs.org/api/packages.html#conditional-exports) in its [`]`package.json`](https://github.com/porsager/postgres/blob/ad0ed4476e09f41f147859cb5a42971d2b99e9c7/package.json#L8-L13): + +```json +"exports": { + "types": "./types/index.d.ts", + "bun": "./src/index.js", + "workerd": "./cf/src/index.js", + "import": "./src/index.js", + "default": "./cjs/src/index.js" +}, +``` + +With such exports, Node.js applications used either `src/index.js` or `cjs/src/index.js` depending if the app use ESM or CJS. + +However we want to use the `workerd` specific entrypoint when using the Cloudflare adapter. +For that, you need to instruct Next.js not to bundle packages as it would use the node conditions by default. + +To do that, list those packages in the `serverExternalPackages` key of `next.config.ts`: + +```ts +// node.config.ts +import type { NextConfig } from "next"; + +const nextConfig: NextConfig = { + serverExternalPackages: ["@prisma/client", ".prisma/client", "postgres"], +}; + +import { initOpenNextCloudflareForDev } from "@opennextjs/cloudflare"; +initOpenNextCloudflareForDev(); + +export default nextConfig; +``` + +### Packages known to have `workerd` specific code + +- `postgres` +- `@prisma/client` (and `.prisma/client`) + +Please report an issue on [the adapter GH repository](https://github.com/opennextjs/opennextjs-cloudflare/issues) to have packages added to this list. From 59db25541146dbe6d4ac5b059ddde60f178ce4a2 Mon Sep 17 00:00:00 2001 From: Victor Berchet Date: Fri, 2 May 2025 16:30:39 +0200 Subject: [PATCH 2/5] fixup! --- pages/cloudflare/howtos/workerd.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/pages/cloudflare/howtos/workerd.mdx b/pages/cloudflare/howtos/workerd.mdx index 47d2a5c..d486882 100644 --- a/pages/cloudflare/howtos/workerd.mdx +++ b/pages/cloudflare/howtos/workerd.mdx @@ -5,7 +5,7 @@ [`workerd`](https://github.com/cloudflare/workerd) is the runtime cloudflare uses to run Workers code. While the [`nodejs_compat`](https://developers.cloudflare.com/workers/configuration/compatibility-flags/#nodejs-compatibility-flag) flag makes `workerd` mostly compatible with Node.js, -there are still minor differences. Some packages publish code for different runtimes to account for those differences. For example, `postgres` has [conditional exports](https://nodejs.org/api/packages.html#conditional-exports) in its [`]`package.json`](https://github.com/porsager/postgres/blob/ad0ed4476e09f41f147859cb5a42971d2b99e9c7/package.json#L8-L13): +there are still minor differences. Some packages publish code for different runtimes to account for those differences. For example, `postgres` has [conditional exports](https://nodejs.org/api/packages.html#conditional-exports) in its [`package.json`](https://github.com/porsager/postgres/blob/ad0ed4476e09f41f147859cb5a42971d2b99e9c7/package.json#L8-L13): ```json "exports": { @@ -22,7 +22,7 @@ With such exports, Node.js applications used either `src/index.js` or `cjs/src/i However we want to use the `workerd` specific entrypoint when using the Cloudflare adapter. For that, you need to instruct Next.js not to bundle packages as it would use the node conditions by default. -To do that, list those packages in the `serverExternalPackages` key of `next.config.ts`: +To do that, list those packages in the `serverExternalPackages` key of your `next.config.ts`: ```ts // node.config.ts From 77eca3d2b8bbf4430bf2574025cbe5e8c03d2369 Mon Sep 17 00:00:00 2001 From: Victor Berchet Date: Fri, 2 May 2025 16:47:42 +0200 Subject: [PATCH 3/5] Update pages/cloudflare/howtos/workerd.mdx Co-authored-by: conico974 --- pages/cloudflare/howtos/workerd.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pages/cloudflare/howtos/workerd.mdx b/pages/cloudflare/howtos/workerd.mdx index d486882..da14f6d 100644 --- a/pages/cloudflare/howtos/workerd.mdx +++ b/pages/cloudflare/howtos/workerd.mdx @@ -41,6 +41,6 @@ export default nextConfig; ### Packages known to have `workerd` specific code - `postgres` -- `@prisma/client` (and `.prisma/client`) +- `@prisma/client` (and the generated `.prisma/client`) Please report an issue on [the adapter GH repository](https://github.com/opennextjs/opennextjs-cloudflare/issues) to have packages added to this list. From c7f13acff52c33dabee11dec1026db0a67d04406 Mon Sep 17 00:00:00 2001 From: Victor Berchet Date: Fri, 2 May 2025 16:47:55 +0200 Subject: [PATCH 4/5] Update pages/cloudflare/howtos/workerd.mdx Co-authored-by: conico974 --- pages/cloudflare/howtos/workerd.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pages/cloudflare/howtos/workerd.mdx b/pages/cloudflare/howtos/workerd.mdx index da14f6d..ce2ec4f 100644 --- a/pages/cloudflare/howtos/workerd.mdx +++ b/pages/cloudflare/howtos/workerd.mdx @@ -17,7 +17,7 @@ there are still minor differences. Some packages publish code for different runt }, ``` -With such exports, Node.js applications used either `src/index.js` or `cjs/src/index.js` depending if the app use ESM or CJS. +With such exports, Node.js applications use either `src/index.js` or `cjs/src/index.js` depending if the app use ESM or CJS. However we want to use the `workerd` specific entrypoint when using the Cloudflare adapter. For that, you need to instruct Next.js not to bundle packages as it would use the node conditions by default. From a75b71a95a9a45e9e6765b8d9ad7bf18bbef5164 Mon Sep 17 00:00:00 2001 From: Victor Berchet Date: Fri, 2 May 2025 17:07:16 +0200 Subject: [PATCH 5/5] Update pages/cloudflare/howtos/workerd.mdx --- pages/cloudflare/howtos/workerd.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pages/cloudflare/howtos/workerd.mdx b/pages/cloudflare/howtos/workerd.mdx index ce2ec4f..9fbb0ff 100644 --- a/pages/cloudflare/howtos/workerd.mdx +++ b/pages/cloudflare/howtos/workerd.mdx @@ -22,7 +22,7 @@ With such exports, Node.js applications use either `src/index.js` or `cjs/src/in However we want to use the `workerd` specific entrypoint when using the Cloudflare adapter. For that, you need to instruct Next.js not to bundle packages as it would use the node conditions by default. -To do that, list those packages in the `serverExternalPackages` key of your `next.config.ts`: +To do that, add those packages in the `serverExternalPackages` key of your `next.config.ts`: ```ts // node.config.ts