0
# CLI Tool
1

2
Command-line interface for executing JavaScript and TypeScript files directly with Vite's transformation pipeline. Provides a `ts-node` alternative with Vite's fast transformation and plugin ecosystem.
3

4
## Basic Usage
5

6
```bash
7
# Execute a TypeScript file
8
npx vite-node index.ts
9

10
# Execute a JavaScript file
11
npx vite-node app.js
12

13
# Execute with command line arguments
14
npx vite-node script.ts arg1 arg2 --flag
15

16
# Execute multiple files
17
npx vite-node file1.ts file2.ts
18
```
19

20
## CLI Options
21

22
### Global Options
23

24
```bash
25
-r, --root <path>        # Use specified root directory
26
-c, --config <path>      # Use specified config file  
27
-m, --mode <mode>        # Set env mode (development, production, etc.)
28
-w, --watch             # Restart on file changes, similar to "nodemon"
29
--script                # Use vite-node as a script runner
30
--options <options>     # Use specified Vite server options
31
-v, --version           # Output the version number
32
-h, --help              # Display help for command
33
```
34

35
### Advanced Configuration
36

37
Complex server options can be passed via the `--options` flag using dot notation:
38

39
```bash
40
# Configure dependency handling
41
npx vite-node --options.deps.inline="module-name" index.ts
42

43
# Configure external dependencies with regex
44
npx vite-node --options.deps.external="/module-regexp/" index.ts
45

46
# Multiple options
47
npx vite-node \
48
  --options.deps.inline="esm-module" \
49
  --options.deps.external="/^lodash/" \
50
  --options.sourcemap=true \
51
  index.ts
52
```
53

54
## Watch Mode
55

56
Automatically restart when files change, similar to `nodemon`:
57

58
```bash
59
# Basic watch mode
60
npx vite-node --watch server.ts
61

62
# Watch with custom config
63
npx vite-node --watch --config vite.config.ts server.ts
64

65
# Watch with environment mode
66
npx vite-node --watch --mode development server.ts
67
```
68

69
**Watch Mode Features:**
70
- Detects file changes using Vite's file watcher
71
- Automatically restarts the process
72
- Preserves command line arguments
73
- Shows clear restart notifications
74
- Handles uncaught exceptions gracefully
75

76
## Script Mode
77

78
Use vite-node as a script runner for executable scripts:
79

80
```bash
81
# Execute in script mode (forwards all arguments to script)
82
npx vite-node --script script.ts arg1 arg2
83

84
# Script mode ignores vite-node options after --script
85
npx vite-node --script script.ts --some-script-flag
86
```
87

88
## Hashbang Support
89

90
Create executable scripts with hashbang:
91

92
```typescript
93
#!/usr/bin/env vite-node --script
94

95
console.log('argv:', process.argv.slice(2));
96
```
97

98
```bash
99
# Make executable
100
chmod +x ./script.ts
101

102
# Run directly
103
./script.ts hello world
104
# Output: argv: [ 'hello', 'world' ]
105
```
106

107
## Configuration Examples
108

109
### Basic Configuration
110

111
```bash
112
# Use custom Vite config
113
npx vite-node --config ./config/vite.config.ts app.ts
114

115
# Set root directory
116
npx vite-node --root ./src app.ts
117

118
# Set environment mode
119
npx vite-node --mode production app.ts
120
```
121

122
### Dependency Handling
123

124
```bash
125
# Inline specific modules for transformation
126
npx vite-node --options.deps.inline="@my-org/package" app.ts
127

128
# Externalize heavy dependencies
129
npx vite-node \
130
  --options.deps.external="lodash" \
131
  --options.deps.external="moment" \
132
  app.ts
133

134
# Use regex patterns for dependency matching
135
npx vite-node --options.deps.inline="/^@my-org\//" app.ts
136
```
137

138
### Debug Options
139

140
```bash
141
# Enable module dumping for debugging
142
npx vite-node --options.debug.dumpModules=true app.ts
143

144
# Dump to custom directory
145
npx vite-node --options.debug.dumpModules="./debug-output" app.ts
146

147
# Load dumped modules instead of transforming
148
npx vite-node --options.debug.loadDumppedModules=true app.ts
149
```
150

151
### Source Map Configuration
152

153
```bash
154
# Enable inline source maps
155
npx vite-node --options.sourcemap=true app.ts
156

157
# Disable source maps
158
npx vite-node --options.sourcemap=false app.ts
159
```
160

161
## Environment Variables
162

163
Configure vite-node behavior using environment variables:
164

165
```bash
166
# Enable debug dumping
167
VITE_NODE_DEBUG_DUMP=true npx vite-node app.ts
168

169
# Load dumped modules
170
VITE_NODE_DEBUG_DUMP=load npx vite-node app.ts
171

172
# Enable runner debugging  
173
VITE_NODE_DEBUG_RUNNER=true npx vite-node app.ts
174

175
# Configure module directories
176
VITE_NODE_DEPS_MODULE_DIRECTORIES=/custom/modules npx vite-node app.ts
177
```
178

179
## Integration Examples
180

181
### Package.json Scripts
182

183
```json
184
{
185
  "scripts": {
186
    "dev": "vite-node --watch src/server.ts",
187
    "start": "vite-node src/server.ts",
188
    "debug": "vite-node --options.debug.dumpModules=true src/app.ts",
189
    "build": "vite-node scripts/build.ts"
190
  }
191
}
192
```
193

194
### Docker Integration
195

196
```dockerfile
197
FROM node:18
198

199
WORKDIR /app
200
COPY package*.json ./
201
RUN npm install
202

203
COPY . .
204

205
# Use vite-node for development
206
CMD ["npx", "vite-node", "--watch", "src/server.ts"]
207
```
208

209
### PM2 Integration
210

211
```json
212
{
213
  "apps": [{
214
    "name": "my-app",
215
    "script": "npx",
216
    "args": ["vite-node", "src/server.ts"],
217
    "instances": 1,
218
    "exec_mode": "fork",
219
    "watch": false,
220
    "env": {
221
      "NODE_ENV": "production"
222
    }
223
  }]
224
}
225
```
226

227
## Performance Tips
228

229
### Optimize Dependencies
230

231
```bash
232
# Externalize heavy dependencies to skip transformation
233
npx vite-node \
234
  --options.deps.external="lodash" \
235
  --options.deps.external="moment" \
236
  --options.deps.external="/^@babel\//" \
237
  app.ts
238
```
239

240
### Cache Configuration
241

242
```bash
243
# Use custom cache directory
244
npx vite-node --options.deps.cacheDir="./.vite-cache" app.ts
245

246
# Enable CJS fallback for compatibility
247
npx vite-node --options.deps.fallbackCJS=true app.ts
248
```
249

250
### Transform Mode Optimization
251

252
```bash
253
# Configure transform modes for better performance
254
npx vite-node \
255
  --options.transformMode.ssr="/\.server\./" \
256
  --options.transformMode.web="/\.client\./" \
257
  app.ts
258
```
259

260
## Error Handling
261

262
Common CLI error scenarios and solutions:
263

264
### Module Resolution Errors
265

266
```bash
267
# Error: Cannot find module 'my-package'
268
# Solution: Configure module directories
269
npx vite-node --options.deps.moduleDirectories="/custom/modules/" app.ts
270
```
271

272
### Transform Errors
273

274
```bash
275
# Error: Transform failed
276
# Solution: Enable debug mode to inspect transformed code
277
VITE_NODE_DEBUG_DUMP=true npx vite-node app.ts
278
# Check .vite-node/dump/ directory for transformed code
279
```
280

281
### Configuration Errors
282

283
```bash
284
# Error: Invalid config
285
# Solution: Use absolute path for config file
286
npx vite-node --config "$(pwd)/vite.config.ts" app.ts
287
```
288

289
## Comparison with Alternatives
290

291
| Feature | vite-node | ts-node | tsx |
292
|---------|-----------|---------|-----|
293
| TypeScript Support | ✅ | ✅ | ✅ |
294
| ESM Support | ✅ | ⚠️ | ✅ |
295
| Vite Plugins | ✅ | ❌ | ❌ |
296
| Transform Speed | ⚡ Fast | 🐌 Slow | ⚡ Fast |
297
| HMR Support | ✅ | ❌ | ❌ |
298
| Vue/Svelte Support | ✅ | ❌ | ❌ |
299
| Watch Mode | ✅ | ✅ | ✅ |
300
| Source Maps | ✅ | ✅ | ✅ |
301
302
## Troubleshooting
303

304
### Common Issues
305

306
1. **Slow Performance**: Externalize heavy dependencies
307
2. **Module Not Found**: Check module directories configuration  
308
3. **Transform Failures**: Enable debug mode to inspect transformed code
309
4. **Watch Mode Issues**: Ensure file permissions and check exclusion patterns
310
5. **Memory Issues**: Configure dependency externalization for large projects
311

312
### Debug Commands
313

314
```bash
315
# Debug transformation issues
316
VITE_NODE_DEBUG_DUMP=true npx vite-node app.ts
317

318
# Debug runner issues  
319
VITE_NODE_DEBUG_RUNNER=true npx vite-node app.ts
320

321
# Debug watcher issues (in watch mode)
322
VITE_TEST_WATCHER_DEBUG=true npx vite-node --watch app.ts
323
```