Handle node:process imports in client, without "UnhandledSchemeError"

[AlanSl]

Goals

1. If a dependency includes import process from 'node:process' it should work just as well as the global process
2. The existing built in polyfill should be used
3. It shouldn't crash out with a UnhandledSchemeError - NextJS knows all about nodeJS's process library and has a polyfill and default behaviours defined

Non-Goals

1. No need for add additional polyfills, bloat etc
2. No need to touch any other node: prefix imports. process is already a special case because NextJS uses process.env in both server and client code.

Background

Currently, importing files that contain imports from node:process works fine on the NextJS server, but when these files are bundled for the client by Webpack 5, it may fail with this error:

Module build failed: UnhandledSchemeError: Reading from "node:process" is not handled by plugins (Unhandled scheme).
Webpack supports "data:" and "file:" URIs by default.
You may need an additional plugin to handle "node:" URIs.

This is surprising because NextJS already handles process in client bundles with built-in default behaviours. Global process and importing from node:process are directly equivalent so it's surprising that one should work and one should fail.

---

There's a workaround but it's quite obscure and I don't think it's documented anywhere:

// in webpack.config.mjs

export default {
  // ...other top level config
  webpack: (config, { isServer, webpack }) => {
    if (isServer) return config

    config.plugins.push(
      new webpack.NormalModuleReplacementPlugin(/^node:process/, (resource) => {
        resource.request = resource.request.replace(/^node:/, '')
      })
    )
    return config
  },
}

Proposal

Automatically map node:process imports to use pre-existing built-in process polyfill (config.resolve.fallback.process) in web builds.

[grilomatheus]

Proposed fix + why it happens

node:process fails on the client because Webpack 5 no longer auto‑polyfills Node core modules, and the node: scheme isn’t resolved to browser shims by default. Next.js only replaces specific process.env.* at build time; it doesn’t provide a full process polyfill for the browser out of the box. That’s why import 'node:process' crashes while process.env.X might appear to “work”. ([webpack][1], [Next.js][2])

Minimal workaround (no extra bloat):

1. Install the tiny browser shim:

npm i process
# or
yarn add process

2. Alias node:process → process/browser only for client builds, and provide it:

// next.config.js (CJS)
module.exports = {
  webpack: (config, { isServer, webpack }) => {
    if (!isServer) {
      config.resolve.alias = {
        ...config.resolve.alias,
        'node:process': 'process/browser',
        process: 'process/browser',
      };
      config.plugins.push(
        new webpack.ProvidePlugin({
          process: ['process/browser'],
        })
      );
    }
    return config;
  },
};

ESM variant:

// next.config.mjs
import { ProvidePlugin } from 'webpack';

export default {
  webpack: (config, { isServer }) => {
    if (!isServer) {
      config.resolve.alias = {
        ...config.resolve.alias,
        'node:process': 'process/browser',
        process: 'process/browser',
      };
      config.plugins.push(new ProvidePlugin({ process: ['process/browser'] }));
    }
    return config;
  },
};

This mirrors your NormalModuleReplacementPlugin idea but makes the intent explicit and routes to the existing lightweight shim.

Why not enable by default?
Auto‑polyfilling Node core in the browser increases bundle size and is something Webpack 5 intentionally removed; frameworks typically avoid restoring it globally. A targeted alias for node:process keeps the fix scoped and small. ([webpack][1], [GitHub][3])

References

• Webpack 5 removed Node polyfills (and recommends explicit shims). ([webpack][1], [GitHub][3])
• Next.js replaces process.env.* at build time (not a full process polyfill). ([Next.js][2])
• node: scheme causing UnhandledSchemeError is a known class of issues. ([GitHub][4])

[icyJoseph]

Hi!

My take here is that, because node: prefix means, this code has to run in Node.js environment, it is a good default to not shim/polyfill.

As the package itself says:

The goal of this module is not to be a full-fledged alternative to the builtin process module. This module mostly exists to provide the nextTick functionality and little more. We keep this module lean because it will often be included by default by tools like browserify when it detects a module has used the process global.

So, if it were to automatically replace node:process imports detected in code packages for browser environments, it'd be opening all sorts of pitfalls.

In a way, you do well to judge those webpack hacks, and the type of LLM answer above, because "bypassing" this error, is but ignoring that your module graph has ended up bringing code meant for the server into the browser.

I am resisting saying but, oh well, node: is a semantic way to state that this code is written for Node.js, if your bundler errors out, you have done something wrong.

It is like having node:fs as part of a module that is bundled for the client - something is wrong there!

• UnhandledSchemeError when dependency uses node:assert imports #28774
• https://www.npmjs.com/package/process