Node Standard Library for Browser

Common errors

• ReferenceError: process is not defined

  cause The `process` global or `Buffer` global (among others) is not automatically polyfilled in the browser environment without proper bundler configuration.
  fix For Webpack, ensure `webpack.ProvidePlugin` is configured to map `process` and `Buffer`. For Rollup/Vite/esbuild, ensure an `inject` plugin (e.g., `@rollup/plugin-inject`) is set up to provide these globals, typically pointing to `node-stdlib-browser`'s implementations.

• Module not found: Error: Can't resolve 'fs' in '...' (or other Node.js built-in modules)

  cause Your bundler is unable to resolve an import for a Node.js standard library module that is being used in a dependency, because the necessary alias or polyfill configuration for `node-stdlib-browser` is missing or incorrect.
  fix Verify that your bundler's configuration (e.g., `webpack.config.js`, `rollup.config.js`, `vite.config.js`) includes `node-stdlib-browser` in its `resolve.alias` section.

• RollupError: "createRequire" is not exported by "node_modules/node-stdlib-browser/esm/mock/empty.js"

  cause This error can occur in Vite/Rollup builds when a dependency attempts to use `createRequire` or other Node.js-specific features from a mocked module provided by `node-stdlib-browser`, and the bundler's configuration for handling ESM/CJS interop or protocol imports is insufficient.
  fix This often points to a larger issue with `node:` protocol imports or mixed ESM/CJS modules. Consider using `vite-plugin-node-polyfills` or carefully reviewing the `node-stdlib-browser` documentation for Vite regarding dynamic imports and plugin enforcement. You might also need to explicitly mark certain modules as external in your bundler configuration if they are causing issues.

• The injected path ".../node_modules/node-stdlib-browser/helpers/esbuild/shim.js" cannot be marked as external

  cause This issue can arise when esbuild or Vite (which uses esbuild) attempts to mark the shim file for `node-stdlib-browser` as external, but it needs to be bundled and injected.
  fix Ensure that the esbuild `inject` configuration correctly references the shim, and that no other configurations are inadvertently marking it as external. This might involve specific plugin order or configuration details depending on your bundler version.

Warnings

• breaking Webpack 5 requires explicit configuration for aliases and global providers. Users migrating from Webpack 4 or earlier will need to update their `webpack.config.js` to include `resolve.alias` and `plugins` for `NodeProtocolUrlPlugin` and `webpack.ProvidePlugin`.
  Fix: Refer to the package's documentation for Webpack configuration, ensuring `resolve.alias` and `webpack.ProvidePlugin` are correctly set up, along with `NodeProtocolUrlPlugin` for `node:` protocol imports.
• gotcha When using ESM configuration in Webpack, specifically for handling unspecified extensions, you might encounter module resolution issues. This often manifests when importing CommonJS modules into an ESM context.
  Fix: Add a rule to your `webpack.config.js` to disable `fullySpecified` for JavaScript modules: `module: { rules: [{ test: /\.m?js$/, resolve: { fullySpecified: false } }] }`.
• gotcha Rollup may emit warnings about circular dependencies when bundling packages that utilize Node.js built-ins. This is a common occurrence in the Node.js ecosystem, and `node-stdlib-browser` provides a helper to manage these warnings.
  Fix: Utilize the `handleCircularDependancyWarning` helper function from `node-stdlib-browser/helpers/rollup/plugin` in your Rollup `onwarn` hook to filter or ignore these specific warnings.
• gotcha When configuring Vite, it is crucial to use dynamic `import()` for `node-stdlib-browser` if your Vite config file is in CommonJS format, to ensure the ESM version of the modules is picked up for proper tree-shaking and dead code removal. The `inject` plugin should also be enforced as 'post'.
  Fix: Ensure your Vite configuration uses `await import('node-stdlib-browser')` and sets `enforce: 'post'` on the `@rollup/plugin-inject` configuration.

Install

• npm install node-stdlib-browser npm
• yarn add node-stdlib-browser yarn
• pnpm add node-stdlib-browser pnpm

Imports

• stdLibBrowser
  wrong:

  import { stdLibBrowser } from 'node-stdlib-browser';

  correct:

  import stdLibBrowser from 'node-stdlib-browser';
  // or
  const stdLibBrowser = require('node-stdlib-browser');

  The main export is a default object containing aliases. Use `import stdLibBrowser from ...` for ESM or `const stdLibBrowser = require(...)` for CJS.
• NodeProtocolUrlPlugin
  wrong:

  import NodeProtocolUrlPlugin from 'node-stdlib-browser/helpers/webpack/plugin';

  correct:

  import { NodeProtocolUrlPlugin } from 'node-stdlib-browser/helpers/webpack/plugin';

  Webpack-specific helper for `node:` protocol imports is a named export from a subpath.
• handleCircularDependancyWarning
  wrong:

  const handleCircularDependancyWarning = require('node-stdlib-browser/helpers/rollup/plugin').handleCircularDependancyWarning;

  correct:

  import { handleCircularDependancyWarning } from 'node-stdlib-browser/helpers/rollup/plugin';

  Rollup-specific helper to suppress circular dependency warnings is a named export.
• esbuildShim

  const esbuildShim = require.resolve('node-stdlib-browser/helpers/esbuild/shim');
  // For direct import if your bundler supports it:
  // import esbuildShim from 'node-stdlib-browser/helpers/esbuild/shim';

  Used for injecting global polyfills in esbuild and Vite configurations; often resolved via `require.resolve`.

Quickstart

This quickstart demonstrates how to configure Vite to use `node-stdlib-browser` for polyfilling Node.js built-in modules in a browser environment. It sets up aliases and injects global variables like `process` and `Buffer` using `@rollup/plugin-inject`.

import { defineConfig } from 'vite';
import inject from '@rollup/plugin-inject';

const esbuildShim = require.resolve('node-stdlib-browser/helpers/esbuild/shim');

export default async () => {
  const { default: stdLibBrowser } = await import('node-stdlib-browser');
  return {
    resolve: {
      alias: stdLibBrowser,
    },
    optimizeDeps: {
      include: ['buffer', 'process'],
    },
    plugins: [
      {
        ...inject({
          global: [esbuildShim, 'global'],
          process: [esbuildShim, 'process'],
          Buffer: [esbuildShim, 'Buffer'],
        }),
        enforce: 'post',
      },
    ],
  };
};