Module build failed: UnhandledSchemeError: Reading from "node:util" is not handled by plugins (Unhandled scheme)

[BrilliantBrilliant is verified member.]

The error UnhandledSchemeError: Reading from "node:util" is not handled by plugins occurs because a Node.js module (like node:util) is being imported in an environment where it isn't properly handled, typically in a frontend context using Webpack, Vite, or similar tools.

Here’s how to fix it:


---

1. Identify the Problem

This error occurs because tools like Webpack or Vite cannot handle Node.js-specific modules (e.g., node:util) in a browser environment.

The node: prefix is a Node.js convention to explicitly import core modules, introduced in Node.js 16+.

Likely causes include:

Using a package designed for Node.js in a browser environment.

A misconfigured bundler (e.g., Webpack, Vite).

An outdated dependency trying to import node: modules.




---

2. Solutions

A. Check for Node.js Dependencies

If you’re using a library that is meant for Node.js (server-side), but you’re trying to use it in a browser environment, you need to either:

1. Use a browser-compatible version of the library.


2. Replace it with an equivalent library that works in the browser.



For example:

Replace util with browser-friendly alternatives like util-polyfill or similar.



---

B. Handle the node: Prefix in Webpack

If you’re using Webpack, ensure the resolve.fallback option is set correctly to handle Node.js core modules in a browser-like environment:

1. Install Polyfills: Install node-polyfill-webpack-plugin or specific polyfills for Node.js modules:

npm install node-polyfill-webpack-plugin

2. Update Webpack Config: Modify webpack.config.js to include the polyfill:

const NodePolyfillPlugin = require('node-polyfill-webpack-plugin');



module.exports = {

  resolve: {

    fallback: {

      util: require.resolve("util/"),

    },

  },

  plugins: [

    new NodePolyfillPlugin(),

  ],

};

3. Alternative Fallbacks: If you don’t want to use node-polyfill-webpack-plugin, you can manually add specific fallbacks:

module.exports = {

  resolve: {

    fallback: {

      util: require.resolve("util/"),

      fs: false, // Disable unsupported modules

    },

  },

};

---

C. Fix Vite Configuration

For Vite, you can configure the vite.config.js file to handle Node.js modules:

1. Install Polyfills:

npm install rollup-plugin-node-polyfills

2. Update Vite Config: Add the polyfill to your vite.config.js:

import { defineConfig } from 'vite';

import nodePolyfills from 'rollup-plugin-node-polyfills';



export default defineConfig({

  plugins: [

    nodePolyfills(),

  ],

  resolve: {

    alias: {

      util: 'util/',

    },

  },

});

---

D. Update Dependencies

Sometimes the issue arises due to outdated dependencies. Update your packages to their latest versions:

npm update

Check your package.json for any dependencies that might be server-specific and confirm they are browser-compatible.


---

E. Replace the node: Prefix

If the node: prefix is unnecessary or causing issues, you can try removing it in your imports. For example:

// Original problematic import

import { someFunction } from 'node:util';



// Replace with:

import { someFunction } from 'util';

This may work in environments where util is automatically handled.


---

F. Use externals for Node.js Modules (if not needed)

If the node:util module is not required in your build (e.g., it's used only in server code), mark it as an external dependency in your bundler config.

For Webpack:

module.exports = {

  externals: {

    util: 'commonjs util',

  },

};

For Vite:

export default defineConfig({

  build: {

    rollupOptions: {

      external: ['util'],

    },

  },

});

---

3. Debugging Steps

Inspect Dependencies: Run npm ls or check your package-lock.json to identify which library depends on node:util.

Verify Environment: Ensure you are using the correct libraries for your target environment (Node.js vs. browser).

Use console.log: Log the module resolution paths to confirm the issue source.



---