vite-node

library6.0.0jsnpmunverified

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.

devops http-networking web-framework

npm install vite-node

github ↗package ↗

INSTALL

IMPORT

SIG · VITE-NODE

vite-node

devopsjavascriptv6.0.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

ViteNodeRunner

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

✗ import { ViteNodeRunner } from 'vite-node'

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

ViteNodeServer

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

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

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

installSourcemapsSupport

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

default import

✓ import viteNode from 'vite-node'

✗ const viteNode = require('vite-node')

vite-node does not export a default; this import is undefined. Use named imports from subpaths.

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')

vite-node --version

Debug

Known issues

breakingv6.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.

affects: >=6.0.0

breakingv5.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.

affects: >=5.0.0

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

affects: *

gotchaThe '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.

affects: *

gotchaOlder 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.

affects: <6.0.0

Errors

Common errors & fixes

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

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.

TypeError: viteNode.default is not a function

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

fix

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

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

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.

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

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.

Upgrade

Version history

6.0.0latest on npm

Audit

Dependencies

viterequiredvite-node relies on Vite's server and plugin system; version compatibility matters.

Agent activity

15 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/antfu-collective/vite-node ↗

packagehttps://www.npmjs.com/package/vite-node ↗