Node.js polyfill for Shopify Oxygen

Hydrogen and Storefront APIs
,
1

Node.js polyfill for Shopify Oxygen

Hi everyone :waving_hand:

We’re currently running a Hydrogen/Remix storefront on Shopify Oxygen, and we’ve hit a blocker around Node.js polyfills for server-side code. I’m trying to understand what the official or recommended approach is for projects deployed to Oxygen.

What we’re trying to solve

We are integrating the @kameleoon/nodejs-sdk package:

https://www.npmjs.com/package/@kameleoon/nodejs-sdk

This SDK depends on Node core modules — in particular crypto — but Shopify Oxygen does not run a Node.js environment. Oxygen runs on Cloudflare Workers, which provide:

  • Web Crypto API instead of Node Crypto
  • A custom Worker runtime instead of Node APIs
  • No access to wrangler.toml or Cloudflare compatibility flags

Because of this, the SDK cannot run without some sort of Node polyfill layer.

What we’ve found so far

1. Cloudflare Workers compatibility flags (ideally what we want)

Cloudflare Workers recommend enabling Node compatibility using:

compatibility_flags = ["nodejs_compat"]

Docs:

However, Shopify Oxygen does not expose the Worker configuration or wrangler.toml, so we can’t enable this flag ourselves. As far as I know, Oxygen has no equivalent mechanism — please correct me if I’m wrong.

This seems like the cleanest solution, but currently not available to us.

2. vite-plugin-node-polyfills

We tried using:

It does polyfill many Node APIs in a Worker/browser environment, but it’s not fully reliable in Oxygen.
Specifically:

  • It depends on node-stdlib-browser
  • That library has unresolved path-resolution issues
  • We had to apply a patch-package workaround just to get builds to succeed

This works, but it feels fragile — and I’m unsure whether this plugin is officially recommended or even compatible with Hydrogen’s Vite build.

3. @remix-run/node globals

Remix provides:

import { installGlobals } from "@remix-run/node";

Docs:

But this only installs WHATWG-standard globals (fetch, Headers, etc.).
It does not polyfill Node.js core modules such as:

  • crypto
  • buffer
  • stream
  • events
  • etc.

So it doesn’t solve compatibility for Node-dependent server libraries.

The question

Is there an official or recommended way to use Node.js polyfills on Shopify Oxygen?

Specifically:

  • Is Oxygen internally enabling Cloudflare’s nodejs_compat flag or planning to expose it?
  • Is vite-plugin-node-polyfills considered compatible or supported for Hydrogen projects?
  • Does Shopify recommend a different polyfill strategy entirely?
  • How should teams integrate Node-dependent NPM packages on Oxygen today?

This feels like a common scenario — many NPM libraries (analytics SDKs, crypto utilities, API clients, etc.) still assume Node core modules exist.

Any guidance or best practices from the Hydrogen/Oxygen team would be hugely appreciated :folded_hands:

Happy to share more details or example configs if helpful.

2

Hey @frankl1nr-squatch! Unfortunately this is a known limitation with Oxygen – it runs on a Cloudflare Workers runtime, not full Node.js, so any library that depends on Node core modules (crypto, buffer, stream, etc.) just won’t work out of the box. And since you can’t access wrangler.toml or enable nodejs_compat flags in Oxygen, there’s no official way to make it work.​

Honestly, the best solution here is for the SDK maintainers to make their library runtime-agnostic (using Web APIs instead of Node-specific ones). That’s really the only reliable path forward for these kinds of integrations on Oxygen.​

That said, if you really need to get this working and want to experiment, you could deploy your Hydrogen store to your own Cloudflare Workers project instead of Oxygen. That way you control wrangler.json and can enable the nodejs_compat flag yourself. We actually have docs on how to do this here: **https://docs.weaverse.io/workers-deployment#1-configure-wrangler-json**​

Hope this helps!

1 Like