vite-node

6.0.0 verified Sat Apr 25 auth: no javascript

Vite-node is a tool that uses Vite as a Node.js runtime, enabling on-demand evaluation of JavaScript/TypeScript files with Vite's plugin pipeline, HMR, and alias resolution. Current stable version is v6.0.0, which requires Node ^20.19.0 || >=22.12.0 and upgrades Vite to v8. The project was originally extracted from Nuxt 3's SSR and previously powered Vitest, but Vitest has migrated to Vite's built-in Environment Module Runner. vite-node remains maintained for legacy ecosystem support, but new projects should consider using Vite's native solution. It features top-level await, shims for __dirname/__filename in ESM, and native Node module access. The library is published as a standalone package on npm and follows a semver release cadence with breaking changes in major versions.

Common errors

error Error: Cannot find module 'vite-node/client' ↓

cause Missing or incorrect import path when using CommonJS require.

fix

Use ESM import: import { ViteNodeRunner } from 'vite-node/client'; or set "type": "module" in package.json.

error TypeError: viteNode.default is not a function ↓

cause Trying to import default from 'vite-node' which has no default export.

fix

Use named exports from subpaths: import { ViteNodeServer } from 'vite-node/server'.

error SyntaxError: The requested module 'vite-node/client' does not provide an export named 'ViteNodeRunner' ↓

cause Using an older version of vite-node where the symbol was exported differently or was not yet available.

fix

Upgrade to vite-node v5+ or check that you are using the correct export name.

error [vite-node] [Error] Failed to resolve module: some-module ↓

cause Vite-node cannot resolve a dependency due to missing config or externalization issues.

fix

Ensure the module is installed and configured in Vite's resolve.alias or optimizeDeps.

Warnings

breaking v6.0.0 upgrades Vite from v5 to v8. The Vite plugin API and internal structures may have changed. ↓

fix Ensure your Vite plugins are compatible with Vite v8. Update if necessary.

breaking v5.0.0 migrated the codebase from the Vitest monorepo to a standalone repo. The package switched to ESM-only. ↓

fix Use ESM imports. If you were using CommonJS require(), switch to import or update your Node.js to support ESM.

deprecated vite-node is effectively superseded by Vite's built-in Environment Module Runner. The maintainers recommend new projects use Vite's native solution. ↓

fix For new projects, consider using Vite's environment API directly: https://vite.dev/guide/api-environment.html

gotcha The 'vite-node' main package entry exports no default; ViteNodeServer and ViteNodeRunner are in subpaths. ↓

fix Always import from 'vite-node/client' or 'vite-node/server' as appropriate.

gotcha Older Vite versions (<6) require manually calling server.pluginContainer.buildStart({}) after createServer. ↓

fix Check Vite version and conditionally call buildStart if major version is less than 6.

Install

npm install vite-node

yarn add vite-node

pnpm add vite-node

Imports

ViteNodeRunner

wrong

import { ViteNodeRunner } from 'vite-node'

correct

import { ViteNodeRunner } from 'vite-node/client'

ViteNodeRunner is exported from 'vite-node/client', not the main entry.

ViteNodeServer

wrong

const { ViteNodeServer } = require('vite-node/server')

correct

import { ViteNodeServer } from 'vite-node/server'

Package is ESM-only since v5. CommonJS require will fail.

installSourcemapsSupport

import { installSourcemapsSupport } from 'vite-node/source-map'

default import
wrong
```
const viteNode = require('vite-node')
```
correct
```
import viteNode from 'vite-node'
```
vite-node does not export a default; this import is undefined. Use named imports from subpaths.

Quickstart

Demonstrates setting up vite-node programmatically: create Vite server, configure ViteNodeServer and ViteNodeRunner, install source map support, and execute a TypeScript file.

import { createServer } from 'vite'
import { ViteNodeRunner } from 'vite-node/client'
import { ViteNodeServer } from 'vite-node/server'
import { installSourcemapsSupport } from 'vite-node/source-map'

const server = await createServer({
  optimizeDeps: {
    noDiscovery: true,
    include: undefined,
  },
})

if (Number(vite.version.split('.')[0]) < 6) {
  await server.pluginContainer.buildStart({})
}

const node = new ViteNodeServer(server)

installSourcemapsSupport({
  getSourceMap: (source) => node.getSourceMap(source),
})

const runner = new ViteNodeRunner({
  root: server.config.root,
  base: server.config.base,
  fetchModule(id) {
    return node.fetchModule(id)
  },
  resolveId(id, importer) {
    return node.resolveId(id, importer)
  },
})

await runner.executeFile('./index.ts')