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
```