[NOT RELEASED!] docs(cloudflare): workerd build condition

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"
 }

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.