Skip to main content
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

new-typescript template screenshot Start from a TypeScript baseline when your extension needs explicit bundler/polyfill tuning.
Repository: extension-js/templates/newtab-typescript

content-typescript

content-typescript template screenshot Use a content-script TypeScript base when Node-dependent libraries run inside page-injected flows.
Repository: extension-js/templates/content-typescript

new-crypto

new-crypto template screenshot See the Web Crypto API (window.crypto.subtle) used directly in a new-tab extension, no polyfill.
Repository: extension-js/templates/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.

node: specifiers and the build error

From the release after 4.1.39, node:fs and fs are the same request, so both spellings get the same answer:
  • crypto, fs, and path resolve to an empty module under either spelling. That includes a subpath such as fs/promises.
  • Any other built-in stops the build. The message names the built-in, the file that imports it, and the resolve.fallback key to set.
  • A require() of a built-in with no stand-in is a warning. The call stays verbatim in the output and throws only if that code path runs. Set EXTENSION_STRICT_REFS=true to fail the build on it.
On 4.1.39 and earlier, a node:-prefixed specifier fails the build for every module, crypto, fs, and path included.

Setting up Node polyfills

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

Add one fallback at a time

You do not need a polyfill plugin for one or two modules. Install the browser packages, then extend resolve.fallback from the config hook. Set a key to false for an empty module. Buffer is a global in Node.js, so provide it with a ProvidePlugin. From the release after 4.1.39, the hook’s second argument carries rspack, the bundler that Extension.js compiles with. Take the plugin class from it, so your project needs no @rspack/core of its own:
extension.config.js
Spread the existing resolve.fallback so the three default keys stay. The trailing slash in require.resolve("buffer/") names the installed package, not the Node.js built-in. A name that exists only with the prefix, such as node:test, has no bare key for resolve.fallback to reach. Replace it with a module of your own through rspack.NormalModuleReplacementPlugin:
extension.config.js

Install optional polyfill packages

Extension APIs vs Node APIs

Setting polyfill: true in CLI/config enables webextension-polyfill, a compatibility layer that gives Chromium browsers older than 148 access to the browser.* API namespace (older than 152 with a devtools_page). Newer versions expose browser natively. 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.
  • From the release after 4.1.39, a node: specifier reads the same resolve.fallback key as its bare name. On earlier versions, it fails the build.

Next steps

Video walkthrough