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..9fbb0ff --- /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 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. + +To do that, add those packages in the `serverExternalPackages` key of your `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 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.