vite-plugin-node-polyfills

0.26.0 verified Sat Apr 25 auth: no javascript

Vite plugin to polyfill Node.js core modules (e.g., 'fs', 'path', 'buffer', 'stream') for browser environments. Current version 0.26.0 supports Vite 2–8. Releases follow semver with active updates. Differentiators: supports `node:` protocol imports, customizable include/exclude/override lists, global polyfill options, and internalized shims to avoid dependency conflicts (since v0.18.0). Ships TypeScript types.

Common errors

error Error: Module "stream" has been externalized for browser compatibility. Cannot access "stream.Readable" in client code. ↓

cause Vite externalizes Node.js core modules by default, but no polyfill is configured.

fix

Add vite-plugin-node-polyfills to vite.config.ts: nodePolyfills({ include: ['stream'] })

error The requested module 'vite-plugin-node-polyfills' does not provide an export named 'default' ↓

cause Using default import instead of named import for `nodePolyfills`.

fix

Use import { nodePolyfills } from 'vite-plugin-node-polyfills'

error Cannot find module 'buffer' or its corresponding type declarations. ↓

cause Missing polyfill for 'buffer' module, or TypeScript cannot resolve types for polyfilled module.

fix

Install vite-plugin-node-polyfills and include 'buffer' in config. For types, install @types/node or add "types": ["node"] to tsconfig.

error Uncaught ReferenceError: process is not defined ↓

cause `process` global is not polyfilled because `globals.process` is not enabled.

fix

In plugin config, set globals: { process: true }

Warnings

breaking Since v0.18.0, buffer and process shims are internalized, preventing version conflicts with Yarn v1. ↓

fix Update to v0.18.0 or later.

deprecated The `global` polyfill may be deprecated in future; prefer explicit polyfilling. ↓

fix Set `globals.global: false` and use other methods to provide global if needed.

gotcha Globals are only polyfilled in development mode by default. For production, `globals.Buffer`, `globals.process` etc. must be explicitly set to `true` or `build`. ↓

fix Set `globals: { Buffer: true, process: true, global: true }` to enable in all modes.

gotcha If you use `include`, modules not listed will NOT be polyfilled, possibly causing runtime errors. ↓

fix Either do not set `include` (polyfills all) or ensure all needed modules are listed.

gotcha The plugin does not polyfill `fs` in the browser; you must provide a custom override (e.g., 'memfs') or avoid using 'fs' in client code. ↓

fix Set `overrides: { fs: 'memfs' }` or replace 'fs' usage with browser-compatible APIs.

Install

npm install vite-plugin-node-polyfills

yarn add vite-plugin-node-polyfills

pnpm add vite-plugin-node-polyfills

Imports

nodePolyfills
wrong
```
import nodePolyfills from 'vite-plugin-node-polyfills'
```
correct
```
import { nodePolyfills } from 'vite-plugin-node-polyfills'
```
Named export, not default. Also available as CommonJS via require, but ESM is preferred in Vite config.

vite.config.ts usage

wrong

export default { plugins: [nodePolyfills()] }

correct

// vite.config.ts
import { defineConfig } from 'vite'
import { nodePolyfills } from 'vite-plugin-node-polyfills'
export default defineConfig({ plugins: [nodePolyfills()] })

Must use defineConfig wrapper for proper type inference and composition.

nodePolyfills options

wrong

nodePolyfills({ include: ['path'] }, { globals: { Buffer: true } })

correct

nodePolyfills({ include: ['path'], globals: { Buffer: true, global: true, process: true }, protocolImports: true })

Options are passed as a single object argument. Separate arguments are incorrect.

type imports

import type { NodePolyfillsOptions } from 'vite-plugin-node-polyfills'

Type is exported for use in TypeScript configs.

Quickstart

Shows basic plugin setup in vite.config.ts and usage of polyfilled modules (path, buffer) in application code.

// vite.config.ts
import { defineConfig } from 'vite'
import { nodePolyfills } from 'vite-plugin-node-polyfills'

export default defineConfig({
  plugins: [
    nodePolyfills({
      // Enable polyfills for specific modules
      include: ['path', 'buffer'],
      // Polyfill globals
      globals: {
        Buffer: true,
        global: true,
        process: true,
      },
      // Support node: protocol imports
      protocolImports: true,
    }),
  ],
})

// Then in your code (e.g., main.ts):
import { resolve } from 'path'
import { Buffer } from 'buffer'
console.log(resolve('/foo', 'bar'))
console.log(Buffer.from('hello').toString('hex'))