Node APIs in browser extensions

Extension.js targets the browser runtime by default. It does not automatically polyfill Node core modules, which keeps bundles small. If a dependency reaches for buffer, stream, or os, you see a resolution error at build time. The sections below explain when to add polyfills and when to choose a browser-native alternative.

When Node polyfills are a good fit

A required dependency needs Node core modules in browser runtime.
You are incrementally migrating code from Node-centric packages.
You can accept larger bundles for specific runtime capabilities.

Template examples

`new-typescript`

Start from a TypeScript baseline when your extension needs explicit bundler/polyfill tuning.

npx extension@latest create my-extension --template=newtab-typescript

pnpx extension@latest create my-extension --template=newtab-typescript

yarn dlx extension@latest create my-extension --template=newtab-typescript

bunx extension@latest create my-extension --template=newtab-typescript

deno run -A npm:extension@latest create my-extension --template=newtab-typescript

Repository: extension-js/examples/newtab-typescript

`content-typescript`

Use a content-script TypeScript base when Node-dependent libraries run inside page-injected flows.

npx extension@latest create my-extension --template=content-typescript

pnpx extension@latest create my-extension --template=content-typescript

yarn dlx extension@latest create my-extension --template=content-typescript

bunx extension@latest create my-extension --template=content-typescript

deno run -A npm:extension@latest create my-extension --template=content-typescript

Repository: extension-js/examples/content-typescript

`new-crypto`

See the Web Crypto API (window.crypto.subtle) used directly in a new-tab extension, no polyfill.

npx extension@latest create my-extension --template=newtab-crypto

pnpx extension@latest create my-extension --template=newtab-crypto

yarn dlx extension@latest create my-extension --template=newtab-crypto

bunx extension@latest create my-extension --template=newtab-crypto

deno run -A npm:extension@latest create my-extension --template=newtab-crypto

Repository: extension-js/examples/newtab-crypto

Default behavior

Build target is browser-first (web).
Resolution prioritizes browser exports (browser, module, main).
crypto, path, and fs are mapped to false, so they resolve to an empty module. The build succeeds and the import fails at runtime instead (for example path.join is undefined).
Every other Node core module, including buffer, stream, os and node:-prefixed specifiers, has no fallback and fails the build with Module not found: Can't resolve.

So a missing Node API shows up in one of two places, and which one depends on the module. Add explicit fallbacks below to handle either case.

Setting up Node polyfills

Use extension.config.js (or .mjs / .cjs) to extend the Rspack configuration and define safe fallbacks.

import NodePolyfillPlugin from "node-polyfill-webpack-plugin";
import { createRequire } from "node:module";

const require = createRequire(import.meta.url);

export default {
  config: (config) => {
    config.resolve = config.resolve || {};
    config.resolve.fallback = {
      ...(config.resolve.fallback || {}),
      crypto: require.resolve("crypto-browserify"),
      path: require.resolve("path-browserify"),
      fs: false,
    };
    config.plugins = config.plugins || [];
    config.plugins.push(new NodePolyfillPlugin());
    return config;
  },
};

Install optional polyfill packages

npm install -D node-polyfill-webpack-plugin crypto-browserify path-browserify

pnpm add -D node-polyfill-webpack-plugin crypto-browserify path-browserify

yarn add -D node-polyfill-webpack-plugin crypto-browserify path-browserify

bun add -d node-polyfill-webpack-plugin crypto-browserify path-browserify

deno add -D npm:node-polyfill-webpack-plugin npm:crypto-browserify npm:path-browserify

Extension APIs vs Node APIs

Setting polyfill: true in CLI/config enables webextension-polyfill, a compatibility layer that gives Chromium browsers access to the browser.* API namespace. It does not enable Node core module polyfills. Use Node polyfills only for libraries that cannot run with standard Web APIs.

Caveats

Do not assume filesystem access in extension runtime; keep fs: false unless you have a specific browser-safe strategy.
Prefer Web Crypto (crypto.subtle) over large Node crypto shims when possible.
Polyfills (browser-compatible replacements for Node APIs) increase bundle size and can affect startup time in extension pages and content scripts.
Some packages using node: specifiers may need explicit fallback handling.

Next steps

Learn how to customize Rspack configuration.
Learn how to manage Extension configuration.

Video walkthrough

⌘I

Introduction

Browser extension fundamentals

Getting started

Commands reference

Features

Browsers

Languages and frameworks

Integrations

Workflows

Machine contracts

Publish to the stores

Debugging

Implementation guide

Community

Node APIs in browser extensions

When Node polyfills are a good fit

Template examples

`new-typescript`

`content-typescript`

`new-crypto`

Default behavior

Setting up Node polyfills

Install optional polyfill packages

Extension APIs vs Node APIs

Caveats

Next steps

Video walkthrough

​When Node polyfills are a good fit

​Template examples

​new-typescript

​content-typescript

​new-crypto

​Default behavior

​Setting up Node polyfills

​Install optional polyfill packages

​Extension APIs vs Node APIs

​Caveats

​Next steps

​Video walkthrough

When Node polyfills are a good fit

Template examples

`new-typescript`

`content-typescript`

`new-crypto`

Default behavior

Setting up Node polyfills

Install optional polyfill packages

Extension APIs vs Node APIs

Caveats

Next steps

Video walkthrough