Polyfill `buffer` usage breaks Cloudflare Workers `nodejs_compat_v2`

[cayter]

Cloudflare Workers will now support better NodeJS compatibility as announced here. However, the package currently relies on iron-webcrypto that uses buffer polyfill and it leads to nodejs_compat_v2 facing the issue below:

Current workaround

Replace buffer/index.js with node:buffer in the node_modules deps before the build step.

[PaulAsjes]

Hi there, can you please provide some reproduction steps? I haven't been able to trigger this error in my CFW example app.

[EnriqueRuvalcaba]

Issue: buffer Module Path Error When Using Cloudflare Workers with Node Compatibility v2

Overview

I'm encountering an issue when using the @workos-inc/node package in a project running on Cloudflare Workers with nodejs_compat_v2. The problem occurs due to a path-related error originating from the buffer module when trying to deploy or run the worker in a development environment.

The error specifically arises when the compatibility_date in wrangler.toml is set to September 23rd, 2024, or later, which activates nodejs_compat_v2. This issue doesn't occur with the older nodejs_compat version, but I cannot use the older compatibility mode due to other dependencies in my actual project that require the latest version.

Tech Stack

• Node.js: v18+
• Cloudflare Workers
• Hono.js: v4.6.3
• Wrangler: v3.78.11
• @workos-inc/node: v7.27.3

Project Description

This is a simple Cloudflare Worker that utilizes the @workos-inc/node library to retrieve a list of organizations via an API call. The Worker is set up using Hono.js, and the environment variables are injected using Cloudflare's bindings.

Below is the code that reproduces the error:

package.json

{
  "name": "workos-error",
  "scripts": {
    "dev": "wrangler dev src/index.ts",
    "deploy": "wrangler deploy --minify src/index.ts"
  },
  "dependencies": {
    "@workos-inc/node": "^7.27.3",
    "hono": "^4.6.3"
  },
  "devDependencies": {
    "@cloudflare/workers-types": "^4.20240529.0",
    "wrangler": "^3.57.2"
  }
}

src/index.ts

import { WorkOS } from "@workos-inc/node";
import { Hono } from "hono";

type Bindings = {
  WORKOS_CLIENT_ID: string;
  WORKOS_API_KEY: string;
};

const app = new Hono<{ Bindings: Bindings }>();

app.get("/", async (c) => {
  const workos = new WorkOS(c.env.WORKOS_API_KEY, {
    clientId: c.env.WORKOS_CLIENT_ID,
  });

  const organizations = await workos.organizations.listOrganizations();

  return c.json(organizations);
});

export default app;

wrangler.toml

With the new nodejs_compat_v2 compatibility flag:

name = "workos-error"
compatibility_date = "2024-09-27"
compatibility_flags = ["nodejs_compat_v2"]

When using the older nodejs_compat compatibility flag, the issue does not occur:

name = "workos-error"
compatibility_date = "2024-09-22"
compatibility_flags = ["nodejs_compat"]

Error logs

⛅️  wrangler  3.78.11
--------------------

[wrangler:inf] Ready on http://localhost:8787
✘ [ERROR] Plugin "unenv-cloudflare" returned a non-absolute path: buffer (set a namespace if this is not a file path)

node_modules/.pnpm/iron-webcrypto@0.2.8/node_modules/iron-webcrypto/dist/index.js:3:23:
3 │ var index_js = require('buffer/index.js');
╵ ~~~~~~~~~~~~~~~~~

✘ [ERROR] Failed to build

Root cause

The error originates from a require statement inside the iron-webcrypto package, which is a dependency of @workos-inc/node. It seems that require('buffer/index.js') is causing issues in the Cloudflare Workers environment when using nodejs_compat_v2. The compatibility update requires paths to be prefixed with node: when referencing native Node.js modules like buffer.

Error location

In the file node_modules/.pnpm/iron-webcrypto@0.2.8/node_modules/iron-webcrypto/dist/index.js, the problematic line is:

var index_js = require('buffer/index.js');

This should be changed to:

var index_js = require('node:buffer');

Steps to reproduce

1. Create a new project:

   pnpm init
   pnpm add @workos-inc/node hono
   pnpm add -D @cloudflare/workers-types wrangler

2. Create a Cloudflare Worker with the provided index.ts file.

3. Update wrangler.toml with the following content:

   name = "workos-error"
   compatibility_date = "2024-09-27"
   compatibility_flags = ["nodejs_compat_v2"]

4. Run the Worker in development mode:

   pnpm run dev

5. Observe the Error:
   The build will fail with the error message mentioned above.

Expected Behavior

The Worker should start without errors and retrieve a list of organizations from the WorkOS API.

Possible Solution

Update the iron-webcrypto dependency to use require('node:buffer') instead of require('buffer/index.js') to align with Node.js module resolution in Cloudflare Workers’ latest compatibility mode (nodejs_compat_v2).

Additional Information

• This issue only occurs with the nodejs_compat_v2 compatibility flag, introduced on September 23rd, 2024, or later.
• Rolling back to the nodejs_compat flag (before the compatibility update) resolves the issue, but this is not feasible for projects that rely on newer features in nodejs_compat_v2.

@PaulAsjes

[PaulAsjes]

Thank you @EnriqueRuvalcaba for the super detailed report! I'll have a look through this and get back to you.

[matheins]

same issue "@workos-inc/node": "^7.10.0" is the last version working for me.

[izumskee]

Hi! Do you have any updates on the issue? I am experiencing the same problem with "@workos-inc/node": "^7.30.0" on Cloudflare Pages in my SvelteKit app, regardless of whether I use node_compat or node_compat_v2.

[fforres]

+1 to this whole thread, I workos is a great tool, but this is limiting for folks building on cloudflare.

In our case we could not implement some observability and distributed tracing from baselime as it requires enabling cloudflare's compatibility_flags

After checking iron-session does seem "just" (famous last words) a package update could be all that's needed, so i tried it and seems to be working on my end.

There's still some issues, made a PR here #1156 explaining what I found, (feel free to do whatever with that PR).

---

I did package/release my hacked-together fork in https://www.npmjs.com/package/@fforres/workos-inc-node.

I STRONGLY recommend that you don't use it, here be dragons and all that. It worked on my case, but if you are truly blocked, be my guest npm i @fforres/workos-inc-node (It just packages what's on that PR)

[amxv]

@PaulAsjes this is still an issue in 7.38.0 :(

i love workos but I dont want to keep patching my deps before every build just to get it to work on cloudflare

[jczstudios]

Blocked by this, was excited to use bc I saw the edge worker support article

Update, was able to get it to work by just using a pnpm override:

  "pnpm": {
    "overrides": {
      "iron-webcrypto": "^1.2.1"
    }
  }

[amcclosky]

@jczstudios Thanks for posting about the workaround that worked for me.