0
# Vite Node
1
2
Vite Node is a Node.js runtime that leverages Vite's pipeline, plugins, resolvers, and transformers to execute JavaScript and TypeScript files on-demand. It provides the engine that powers Vitest testing framework and Nuxt 3 Dev SSR, offering features like on-demand evaluation, out-of-box ESM and TypeScript support, hot module replacement (HMR), and separate server/client architecture.
3
4
## Package Information
5
6
- **Package Name**: vite-node
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install vite-node`
10
11
## Core Imports
12
13
```typescript
14
import { ViteNodeRunner } from "vite-node/client";
15
import { ViteNodeServer } from "vite-node/server";
16
import { installSourcemapsSupport } from "vite-node/source-map";
17
```
18
19
For CommonJS:
20
21
```javascript
22
const { ViteNodeRunner } = require("vite-node/client");
23
const { ViteNodeServer } = require("vite-node/server");
24
```
25
26
## Basic Usage
27
28
```typescript
29
import { createServer } from "vite";
30
import { ViteNodeRunner } from "vite-node/client";
31
import { ViteNodeServer } from "vite-node/server";
32
import { installSourcemapsSupport } from "vite-node/source-map";
33
34
// Create vite server
35
const server = await createServer({
36
optimizeDeps: {
37
disabled: true, // Recommended for vite-node
38
},
39
});
40
41
// Create vite-node server
42
const node = new ViteNodeServer(server);
43
44
// Install source map support for better error traces
45
installSourcemapsSupport({
46
getSourceMap: source => node.getSourceMap(source),
47
});
48
49
// Create vite-node runner
50
const runner = new ViteNodeRunner({
51
root: server.config.root,
52
base: server.config.base,
53
fetchModule(id) {
54
return node.fetchModule(id);
55
},
56
resolveId(id, importer) {
57
return node.resolveId(id, importer);
58
},
59
});
60
61
// Execute a TypeScript file
62
await runner.executeFile('./example.ts');
63
64
// Close the server
65
await server.close();
66
```
67
68
## Architecture
69
70
Vite Node is built around a server/client architecture with several key components:
71
72
- **Server Component**: `ViteNodeServer` handles module transformation, resolution, and caching using Vite's pipeline
73
- **Client Component**: `ViteNodeRunner` executes transformed modules with proper isolation and context management
74
- **Module Cache**: Smart caching system with dependency tracking and invalidation capabilities
75
- **Hot Module Replacement**: Full HMR support for development workflows with file watching
76
- **Source Maps**: Inline source map support for debugging with accurate stack traces
77
- **CLI Tool**: Command-line interface for direct script execution similar to `ts-node`
78
79
## Capabilities
80
81
### Client Runtime
82
83
Core module execution engine that runs transformed JavaScript/TypeScript code with proper context isolation and dependency management.
84
85
```typescript { .api }
86
class ViteNodeRunner {
87
constructor(options: ViteNodeRunnerOptions);
88
executeFile(file: string): Promise<any>;
89
executeId(rawId: string): Promise<any>;
90
}
91
92
interface ViteNodeRunnerOptions {
93
root: string;
94
fetchModule: FetchFunction;
95
resolveId?: ResolveIdFunction;
96
createHotContext?: CreateHotContextFunction;
97
base?: string;
98
moduleCache?: ModuleCacheMap;
99
interopDefault?: boolean;
100
requestStubs?: Record<string, any>;
101
debug?: boolean;
102
}
103
```
104
105
[Client Runtime](./client.md)
106
107
### Server Integration
108
109
Server-side integration with Vite that handles module transformation, resolution, and caching through Vite's plugin system.
110
111
```typescript { .api }
112
class ViteNodeServer {
113
constructor(server: ViteDevServer, options?: ViteNodeServerOptions);
114
fetchModule(id: string, transformMode?: 'web' | 'ssr'): Promise<FetchResult>;
115
resolveId(id: string, importer?: string, transformMode?: 'web' | 'ssr'): Promise<ViteNodeResolveId | null>;
116
getSourceMap(source: string): EncodedSourceMap | null;
117
}
118
119
interface ViteNodeServerOptions {
120
sourcemap?: 'inline' | boolean;
121
deps?: DepsHandlingOptions;
122
transformMode?: {
123
ssr?: RegExp[];
124
web?: RegExp[];
125
};
126
debug?: DebuggerOptions;
127
}
128
```
129
130
[Server Integration](./server.md)
131
132
### Utilities
133
134
Path handling, module resolution, and platform utilities for working with file systems and import paths.
135
136
```typescript { .api }
137
function normalizeModuleId(id: string): string;
138
function isNodeBuiltin(id: string): boolean;
139
function toFilePath(id: string, root: string): { path: string; exists: boolean };
140
function slash(str: string): string;
141
```
142
143
[Utilities](./utils.md)
144
145
### Hot Module Replacement
146
147
Complete HMR implementation with event handling, module invalidation, and hot context management for development workflows.
148
149
```typescript { .api }
150
function createHotContext(
151
runner: ViteNodeRunner,
152
emitter: HMREmitter,
153
files: string[],
154
ownerPath: string
155
): HotContext;
156
157
function handleMessage(
158
runner: ViteNodeRunner,
159
emitter: HMREmitter,
160
files: string[],
161
payload: HMRPayload
162
): Promise<void>;
163
```
164
165
[Hot Module Replacement](./hmr.md)
166
167
### Source Maps
168
169
Inline source map support for debugging with accurate stack traces in transformed code.
170
171
```typescript { .api }
172
function installSourcemapsSupport(options: InstallSourceMapSupportOptions): void;
173
function withInlineSourcemap(result: TransformResult, options: {
174
root: string;
175
filepath: string;
176
noFirstLineMapping?: boolean;
177
}): TransformResult;
178
179
interface InstallSourceMapSupportOptions {
180
getSourceMap: (source: string) => EncodedSourceMap | null | undefined;
181
}
182
```
183
184
[Source Maps](./source-maps.md)
185
186
### CLI Tool
187
188
Command-line interface for executing JavaScript and TypeScript files directly with Vite's transformation pipeline.
189
190
```bash
191
# Execute a TypeScript file
192
npx vite-node index.ts
193
194
# Watch mode with automatic restart
195
npx vite-node --watch index.ts
196
197
# Script mode for hashbang usage
198
npx vite-node --script script.ts
199
200
# With configuration
201
npx vite-node --config vite.config.ts index.ts
202
```
203
204
[CLI Tool](./cli.md)
205
206
### Constants
207
208
File type constants and regular expressions for asset detection and CSS language identification.
209
210
```typescript { .api }
211
const KNOWN_ASSET_TYPES: string[];
212
const KNOWN_ASSET_RE: RegExp;
213
const CSS_LANGS_RE: RegExp;
214
```
215
216
**Import:**
217
218
```typescript
219
import { KNOWN_ASSET_TYPES, KNOWN_ASSET_RE, CSS_LANGS_RE } from "vite-node/constants";
220
```
221
222
## Core Types
223
224
```typescript { .api }
225
type Nullable<T> = T | null | undefined;
226
type Arrayable<T> = T | Array<T>;
227
type Awaitable<T> = T | PromiseLike<T>;
228
229
type FetchFunction = (id: string) => Promise<FetchResult>;
230
type ResolveIdFunction = (id: string, importer?: string) => Awaitable<ViteNodeResolveId | null | undefined | void>;
231
type CreateHotContextFunction = (runner: ViteNodeRunner, url: string) => HotContext;
232
233
interface FetchResult {
234
code?: string;
235
externalize?: string;
236
map?: EncodedSourceMap | null;
237
}
238
239
interface ViteNodeResolveId {
240
external?: boolean | 'absolute' | 'relative';
241
id: string;
242
meta?: Record<string, any> | null;
243
moduleSideEffects?: boolean | 'no-treeshake' | null;
244
syntheticNamedExports?: boolean | string | null;
245
}
246
247
interface ModuleCache {
248
promise?: Promise<any>;
249
exports?: any;
250
evaluated?: boolean;
251
resolving?: boolean;
252
code?: string;
253
map?: EncodedSourceMap;
254
importers?: Set<string>;
255
imports?: Set<string>;
256
}
257
258
interface DepsHandlingOptions {
259
external?: (string | RegExp)[];
260
inline?: (string | RegExp)[] | true;
261
inlineFiles?: string[];
262
moduleDirectories?: string[];
263
cacheDir?: string;
264
fallbackCJS?: boolean;
265
}
266
267
interface DebuggerOptions {
268
dumpModules?: boolean | string;
269
loadDumppedModules?: boolean;
270
}
271
```