Modern Node Polyfills

Common errors

• Error: Cannot find module 'esbuild'

  cause The `esbuild` peer dependency is missing from your project's `node_modules`.
  fix Install esbuild as a direct dependency: `npm install esbuild` or `yarn add esbuild`.

• ERR_MODULE_NOT_FOUND or Cannot read properties of undefined (reading 'polyfillPath') when using require()

  cause The package is primarily designed for ESM. Attempting to use CommonJS `require()` might fail in environments or bundlers not configured to handle it correctly for this library.
  fix Migrate your import statements to ESM: `import { polyfillPath } from 'modern-node-polyfills';`. Ensure your project's `package.json` specifies `"type": "module"` if running in Node.js, or your bundler is configured for ESM.

• ReferenceError: process is not defined (or Buffer is not defined, global is not defined)

  cause Your code is attempting to access Node.js global variables that have not been polyfilled or injected into the environment.
  fix Utilize the `polyfillGlobals` function to automatically replace these expressions in your code before execution, or use the `inject` function for more granular control over specific globals.

Warnings

• gotcha This package requires `esbuild` as a peer dependency, but it's not automatically installed. Failure to install `esbuild` will lead to runtime errors.
  Fix: Ensure `esbuild` is installed in your project: `npm install esbuild` or `yarn add esbuild`.
• gotcha modern-node-polyfills is designed to provide *subset* polyfills for Node.js native modules in non-Node environments (e.g., browsers, Cloudflare Workers, Deno). It does not aim for full Node.js API parity for all modules or their deeper functionalities.
  Fix: Review the list of supported modules and their features (linked in the README) to ensure the specific Node.js APIs your application uses are covered. Test thoroughly in your target environment.
• gotcha Polyfills for `__filename` and `__dirname` are static or user-configurable, not dynamically resolved based on the current file path like in a true Node.js environment.
  Fix: When using `polyfillGlobals` or `inject` for `__filename` and `__dirname`, explicitly configure their desired string values via the options object to match your deployment context.

Install

• npm install modern-node-polyfills npm
• yarn add modern-node-polyfills yarn
• pnpm add modern-node-polyfills pnpm

Imports

• polyfillPath
  wrong:

  const { polyfillPath } = require('modern-node-polyfills')

  correct:

  import { polyfillPath } from 'modern-node-polyfills'

  The library primarily uses ESM `import` syntax. While some bundler configurations might support `require()`, it's not the officially recommended or explicitly supported import style.
• inject
  wrong:

  import inject from 'modern-node-polyfills'

  correct:

  import { inject } from 'modern-node-polyfills'

  All public utilities are named exports; there is no default export. This function helps replace global expressions and module imports within code.
• polyfillGlobals
  wrong:

  const polyfillGlobals = require('modern-node-polyfills').polyfillGlobals

  correct:

  import { polyfillGlobals } from 'modern-node-polyfills'

  This utility is crucial for automatically replacing common Node.js global expressions (like `process`, `Buffer`, `__filename`) with their polyfilled equivalents.

Quickstart

This quickstart demonstrates how to use `polyfillGlobals` to transform code containing Node.js globals (`process`, `Buffer`, `global`, `__filename`, `__dirname`) into a version suitable for non-Node environments, including custom paths for file-system specific globals.

import { polyfillGlobals } from 'modern-node-polyfills';

const browserCode = `
    console.log(global);
    console.log(process.env.NODE_ENV);
    const buf = Buffer.from('hello');
    console.log(buf.toString());
    console.log(__filename);
    console.log(__dirname);
`;

async function transformAndLog() {
  try {
    const polyfilledContent = await polyfillGlobals(
      browserCode,
      { 
        __filename: '/app/index.js',
        __dirname: '/app' 
      }
    );
    console.log('--- Original Code ---\n' + browserCode);
    console.log('\n--- Polyfilled Content ---\n' + polyfilledContent);
    // In a real browser/edge environment, you would now execute polyfilledContent
  } catch (error) {
    console.error('Error during polyfill:', error);
  }
}

transformAndLog();