0
# Vite Plugin Node Polyfills
1
2
A Vite plugin to polyfill Node's Core Modules for browser environments. This plugin enables Node.js packages to run in browsers by providing polyfills for all Node.js built-in modules, with support for the modern `node:` protocol imports and flexible configuration options.
3
4
## Package Information
5
6
- **Package Name**: vite-plugin-node-polyfills
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install --save-dev vite-plugin-node-polyfills`
10
11
## Core Imports
12
13
```typescript
14
import { nodePolyfills } from "vite-plugin-node-polyfills";
15
```
16
17
For CommonJS:
18
19
```javascript
20
const { nodePolyfills } = require("vite-plugin-node-polyfills");
21
```
22
23
For shims (when using specific polyfills directly):
24
25
```typescript
26
import "vite-plugin-node-polyfills/shims/buffer";
27
import "vite-plugin-node-polyfills/shims/global";
28
import "vite-plugin-node-polyfills/shims/process";
29
```
30
31
## Basic Usage
32
33
```typescript
34
import { defineConfig } from "vite";
35
import { nodePolyfills } from "vite-plugin-node-polyfills";
36
37
export default defineConfig({
38
plugins: [
39
nodePolyfills(),
40
],
41
});
42
```
43
44
With configuration:
45
46
```typescript
47
import { defineConfig } from "vite";
48
import { nodePolyfills } from "vite-plugin-node-polyfills";
49
50
export default defineConfig({
51
plugins: [
52
nodePolyfills({
53
// Include specific modules only
54
include: ["path", "fs"],
55
// Exclude specific modules
56
exclude: ["http"],
57
// Configure global polyfills
58
globals: {
59
Buffer: true,
60
global: "dev", // Only in development
61
process: false, // Disable process polyfill
62
},
63
// Override default polyfills
64
overrides: {
65
fs: "memfs", // Use memfs instead of default fs polyfill
66
},
67
// Enable node: protocol polyfills
68
protocolImports: true,
69
}),
70
],
71
});
72
```
73
74
## Architecture
75
76
The plugin works by:
77
78
1. **Module Resolution**: Intercepts imports of Node.js core modules and redirects them to browser-compatible polyfills
79
2. **Global Injection**: Optionally injects global variables (Buffer, global, process) into the browser environment
80
3. **Protocol Support**: Handles both traditional imports (`import "fs"`) and modern protocol imports (`import "node:fs"`)
81
4. **Build Integration**: Configures Vite's build pipeline to include polyfills and handle circular dependencies
82
5. **Development Support**: Provides banner injection for isolated scripts (like Vue SFCs) in development mode
83
84
## Capabilities
85
86
### Main Plugin Function
87
88
Creates a Vite plugin instance with Node.js polyfill support.
89
90
```typescript { .api }
91
/**
92
* Returns a Vite plugin to polyfill Node's Core Modules for browser environments.
93
* Supports node: protocol imports and provides flexible configuration options.
94
* @param options - Configuration options for the plugin
95
* @returns Vite Plugin object
96
*/
97
function nodePolyfills(options?: PolyfillOptions): Plugin;
98
99
interface PolyfillOptions {
100
/** Specific modules to include. If empty, includes all modules */
101
include?: ModuleNameWithoutNodePrefix[];
102
/** Specific modules to exclude from polyfilling */
103
exclude?: ModuleNameWithoutNodePrefix[];
104
/** Configuration for global polyfills */
105
globals?: {
106
Buffer?: BooleanOrBuildTarget;
107
global?: BooleanOrBuildTarget;
108
process?: BooleanOrBuildTarget;
109
};
110
/** Alternative modules to use in place of default polyfills */
111
overrides?: { [Key in ModuleNameWithoutNodePrefix]?: string };
112
/** Whether the Node protocol version should be polyfilled too (default: true) */
113
protocolImports?: boolean;
114
}
115
116
type BooleanOrBuildTarget = boolean | BuildTarget;
117
type BuildTarget = "build" | "dev";
118
type ModuleName = keyof typeof stdLibBrowser;
119
type ModuleNameWithoutNodePrefix<T = ModuleName> = T extends `node:${infer P}` ? P : never;
120
```
121
122
**Usage Examples:**
123
124
```typescript
125
// Include only specific polyfills
126
nodePolyfills({
127
include: ["fs", "path", "crypto"],
128
})
129
130
// Exclude specific polyfills
131
nodePolyfills({
132
exclude: ["http", "https", "net"],
133
})
134
135
// Configure globals for different build modes
136
nodePolyfills({
137
globals: {
138
Buffer: "build", // Only in production builds
139
global: true, // Always available
140
process: "dev", // Only in development
141
},
142
})
143
144
// Override default polyfills with custom implementations
145
nodePolyfills({
146
overrides: {
147
fs: "memfs", // Use memfs for filesystem operations
148
crypto: "crypto-js", // Use crypto-js for cryptographic functions
149
},
150
})
151
152
// Disable node: protocol imports
153
nodePolyfills({
154
protocolImports: false,
155
})
156
```
157
158
### Shim Modules
159
160
Direct access to specific polyfills for manual integration.
161
162
```typescript { .api }
163
// Buffer shim exports
164
export {
165
Blob,
166
BlobOptions,
167
Buffer,
168
File,
169
FileOptions,
170
INSPECT_MAX_BYTES,
171
SlowBuffer,
172
TranscodeEncoding,
173
atob,
174
btoa,
175
constants,
176
isAscii,
177
isUtf8,
178
kMaxLength,
179
kStringMaxLength,
180
resolveObjectURL,
181
transcode,
182
} from "vite-plugin-node-polyfills/shims/buffer";
183
184
// Global shim export
185
export { global } from "vite-plugin-node-polyfills/shims/global";
186
187
// Process shim export
188
export { process } from "vite-plugin-node-polyfills/shims/process";
189
```
190
191
**Usage Examples:**
192
193
```typescript
194
// Direct buffer import
195
import { Buffer } from "vite-plugin-node-polyfills/shims/buffer";
196
197
// Direct global import
198
import { global } from "vite-plugin-node-polyfills/shims/global";
199
200
// Direct process import
201
import { process } from "vite-plugin-node-polyfills/shims/process";
202
```
203
204
## Supported Node.js Core Modules
205
206
The plugin provides polyfills for all Node.js core modules:
207
208
**Stream Modules:**
209
- `_stream_duplex`, `_stream_passthrough`, `_stream_readable`, `_stream_transform`, `_stream_writable`
210
211
**Core Modules:**
212
- `assert`, `buffer`, `child_process`, `cluster`, `console`, `constants`, `crypto`
213
- `dgram`, `dns`, `domain`, `events`, `fs`, `http`, `http2`, `https`
214
- `module`, `net`, `os`, `path`, `process`, `punycode`, `querystring`
215
- `readline`, `repl`, `stream`, `string_decoder`, `sys`, `timers`, `timers/promises`
216
- `tls`, `tty`, `url`, `util`, `vm`, `zlib`
217
218
When `protocolImports` is enabled (default), also supports `node:` prefixed imports for all modules (e.g., `node:fs`, `node:path`, `node:crypto`).
219
220
## Types
221
222
```typescript { .api }
223
type BuildTarget = "build" | "dev";
224
225
type BooleanOrBuildTarget = boolean | BuildTarget;
226
227
type ModuleName = keyof typeof stdLibBrowser;
228
229
type ModuleNameWithoutNodePrefix<T = ModuleName> = T extends `node:${infer P}` ? P : never;
230
231
interface PolyfillOptions {
232
include?: ModuleNameWithoutNodePrefix[];
233
exclude?: ModuleNameWithoutNodePrefix[];
234
globals?: {
235
Buffer?: BooleanOrBuildTarget;
236
global?: BooleanOrBuildTarget;
237
process?: BooleanOrBuildTarget;
238
};
239
overrides?: { [Key in ModuleNameWithoutNodePrefix]?: string };
240
protocolImports?: boolean;
241
}
242
243
interface PolyfillOptionsResolved {
244
include: ModuleNameWithoutNodePrefix[];
245
exclude: ModuleNameWithoutNodePrefix[];
246
globals: {
247
Buffer: BooleanOrBuildTarget;
248
global: BooleanOrBuildTarget;
249
process: BooleanOrBuildTarget;
250
};
251
overrides: { [Key in ModuleNameWithoutNodePrefix]?: string };
252
protocolImports: boolean;
253
}
254
```
255
256
## Error Handling
257
258
The plugin handles common polyfill-related issues:
259
260
- **Circular Dependencies**: Automatically suppresses circular dependency warnings from Node.js polyfills
261
- **Missing Modules**: Gracefully handles cases where polyfills are not available for specific modules
262
- **Build Mode Detection**: Correctly applies different polyfill strategies for development vs production builds
263
- **Protocol Import Resolution**: Properly resolves both traditional and `node:` protocol imports