tessl/npm-vite-node

Vite as Node.js runtime that enables on-demand evaluation with full ESM and TypeScript support

—

Pending

Overview

Eval results

Files

CLI Tool

Name: tessl/npm-vite-node
Author: tessl

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.

Basic Usage

# Execute a TypeScript file
npx vite-node index.ts

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

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

# Execute multiple files
npx vite-node file1.ts file2.ts

CLI Options

Global Options

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

Advanced Configuration

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

# Configure dependency handling
npx vite-node --options.deps.inline="module-name" index.ts

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

# Multiple options
npx vite-node \
  --options.deps.inline="esm-module" \
  --options.deps.external="/^lodash/" \
  --options.sourcemap=true \
  index.ts

Watch Mode

Automatically restart when files change, similar to nodemon:

# Basic watch mode
npx vite-node --watch server.ts

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

# Watch with environment mode
npx vite-node --watch --mode development server.ts

Watch Mode Features:

Detects file changes using Vite's file watcher
Automatically restarts the process
Preserves command line arguments
Shows clear restart notifications
Handles uncaught exceptions gracefully

Script Mode

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

# Execute in script mode (forwards all arguments to script)
npx vite-node --script script.ts arg1 arg2

# Script mode ignores vite-node options after --script
npx vite-node --script script.ts --some-script-flag

Hashbang Support

Create executable scripts with hashbang:

#!/usr/bin/env vite-node --script

console.log('argv:', process.argv.slice(2));

# Make executable
chmod +x ./script.ts

# Run directly
./script.ts hello world
# Output: argv: [ 'hello', 'world' ]

Configuration Examples

Basic Configuration

# Use custom Vite config
npx vite-node --config ./config/vite.config.ts app.ts

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

# Set environment mode
npx vite-node --mode production app.ts

Dependency Handling

# Inline specific modules for transformation
npx vite-node --options.deps.inline="@my-org/package" app.ts

# Externalize heavy dependencies
npx vite-node \
  --options.deps.external="lodash" \
  --options.deps.external="moment" \
  app.ts

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

Debug Options

# Enable module dumping for debugging
npx vite-node --options.debug.dumpModules=true app.ts

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

# Load dumped modules instead of transforming
npx vite-node --options.debug.loadDumppedModules=true app.ts

Source Map Configuration

# Enable inline source maps
npx vite-node --options.sourcemap=true app.ts

# Disable source maps
npx vite-node --options.sourcemap=false app.ts

Environment Variables

Configure vite-node behavior using environment variables:

# Enable debug dumping
VITE_NODE_DEBUG_DUMP=true npx vite-node app.ts

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

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

# Configure module directories
VITE_NODE_DEPS_MODULE_DIRECTORIES=/custom/modules npx vite-node app.ts

Integration Examples

Package.json Scripts

{
  "scripts": {
    "dev": "vite-node --watch src/server.ts",
    "start": "vite-node src/server.ts",
    "debug": "vite-node --options.debug.dumpModules=true src/app.ts",
    "build": "vite-node scripts/build.ts"
  }
}

Docker Integration

FROM node:18

WORKDIR /app
COPY package*.json ./
RUN npm install

COPY . .

# Use vite-node for development
CMD ["npx", "vite-node", "--watch", "src/server.ts"]

PM2 Integration

{
  "apps": [{
    "name": "my-app",
    "script": "npx",
    "args": ["vite-node", "src/server.ts"],
    "instances": 1,
    "exec_mode": "fork",
    "watch": false,
    "env": {
      "NODE_ENV": "production"
    }
  }]
}

Performance Tips

Optimize Dependencies

# Externalize heavy dependencies to skip transformation
npx vite-node \
  --options.deps.external="lodash" \
  --options.deps.external="moment" \
  --options.deps.external="/^@babel\//" \
  app.ts

Cache Configuration

# Use custom cache directory
npx vite-node --options.deps.cacheDir="./.vite-cache" app.ts

# Enable CJS fallback for compatibility
npx vite-node --options.deps.fallbackCJS=true app.ts

Transform Mode Optimization

# Configure transform modes for better performance
npx vite-node \
  --options.transformMode.ssr="/\.server\./" \
  --options.transformMode.web="/\.client\./" \
  app.ts

Error Handling

Common CLI error scenarios and solutions:

Module Resolution Errors

# Error: Cannot find module 'my-package'
# Solution: Configure module directories
npx vite-node --options.deps.moduleDirectories="/custom/modules/" app.ts

Transform Errors

# Error: Transform failed
# Solution: Enable debug mode to inspect transformed code
VITE_NODE_DEBUG_DUMP=true npx vite-node app.ts
# Check .vite-node/dump/ directory for transformed code

Configuration Errors

# Error: Invalid config
# Solution: Use absolute path for config file
npx vite-node --config "$(pwd)/vite.config.ts" app.ts

Comparison with Alternatives

Feature	vite-node	ts-node	tsx
TypeScript Support	✅	✅	✅
ESM Support	✅	⚠️	✅
Vite Plugins	✅	❌	❌
Transform Speed	⚡ Fast	🐌 Slow	⚡ Fast
HMR Support	✅	❌	❌
Vue/Svelte Support	✅	❌	❌
Watch Mode	✅	✅	✅
Source Maps	✅	✅	✅

Troubleshooting

Common Issues

Slow Performance: Externalize heavy dependencies
Module Not Found: Check module directories configuration
Transform Failures: Enable debug mode to inspect transformed code
Watch Mode Issues: Ensure file permissions and check exclusion patterns
Memory Issues: Configure dependency externalization for large projects

Debug Commands

# Debug transformation issues
VITE_NODE_DEBUG_DUMP=true npx vite-node app.ts

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

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

Install with Tessl CLI