Registry /
devops / vite-plugin-node-polyfills
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
nodePolyfills
✓ import { nodePolyfills } from 'vite-plugin-node-polyfills'
✗ 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
✓ // vite.config.ts
import { defineConfig } from 'vite'
import { nodePolyfills } from 'vite-plugin-node-polyfills'
export default defineConfig({ plugins: [nodePolyfills()] })
✗ export default { plugins: [nodePolyfills()] }
Must use defineConfig wrapper for proper type inference and composition.
nodePolyfills options
✓ nodePolyfills({ include: ['path'], globals: { Buffer: true, global: true, process: true }, protocolImports: true })
✗ nodePolyfills({ include: ['path'] }, { globals: { Buffer: 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.
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'))
Errors
Common errors & fixes
Error: Module "stream" has been externalized for browser compatibility. Cannot access "stream.Readable" in client code.
Vite externalizes Node.js core modules by default, but no polyfill is configured.
fixAdd vite-plugin-node-polyfills to vite.config.ts: `nodePolyfills({ include: ['stream'] })` The requested module 'vite-plugin-node-polyfills' does not provide an export named 'default'
Using default import instead of named import for `nodePolyfills`.
fixUse `import { nodePolyfills } from 'vite-plugin-node-polyfills'` Cannot find module 'buffer' or its corresponding type declarations.
Missing polyfill for 'buffer' module, or TypeScript cannot resolve types for polyfilled module.
fixInstall vite-plugin-node-polyfills and include 'buffer' in config. For types, install `@types/node` or add `"types": ["node"]` to tsconfig.
Uncaught ReferenceError: process is not defined
`process` global is not polyfilled because `globals.process` is not enabled.
fixIn plugin config, set `globals: { process: true }` Audit
Dependencies
viterequiredpeerdep: works with Vite 2–8
node-stdlib-browserrequiredunderlying polyfill library used for module shims