{"id":20657,"library":"vite-node","title":"vite-node","description":"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.","status":"active","version":"6.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/antfu-collective/vite-node","tags":["javascript"],"install":[{"cmd":"npm install vite-node","lang":"bash","label":"npm"},{"cmd":"yarn add vite-node","lang":"bash","label":"yarn"},{"cmd":"pnpm add vite-node","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"vite-node relies on Vite's server and plugin system; version compatibility matters.","package":"vite","optional":false}],"imports":[{"note":"ViteNodeRunner is exported from 'vite-node/client', not the main entry.","wrong":"import { ViteNodeRunner } from 'vite-node'","symbol":"ViteNodeRunner","correct":"import { ViteNodeRunner } from 'vite-node/client'"},{"note":"Package is ESM-only since v5. CommonJS require will fail.","wrong":"const { ViteNodeServer } = require('vite-node/server')","symbol":"ViteNodeServer","correct":"import { ViteNodeServer } from 'vite-node/server'"},{"symbol":"installSourcemapsSupport","correct":"import { installSourcemapsSupport } from 'vite-node/source-map'"},{"note":"vite-node does not export a default; this import is undefined. Use named imports from subpaths.","wrong":"const viteNode = require('vite-node')","symbol":"default import","correct":"import viteNode from 'vite-node'"}],"quickstart":{"code":"import { createServer } from 'vite'\nimport { ViteNodeRunner } from 'vite-node/client'\nimport { ViteNodeServer } from 'vite-node/server'\nimport { installSourcemapsSupport } from 'vite-node/source-map'\n\nconst server = await createServer({\n  optimizeDeps: {\n    noDiscovery: true,\n    include: undefined,\n  },\n})\n\nif (Number(vite.version.split('.')[0]) < 6) {\n  await server.pluginContainer.buildStart({})\n}\n\nconst node = new ViteNodeServer(server)\n\ninstallSourcemapsSupport({\n  getSourceMap: (source) => node.getSourceMap(source),\n})\n\nconst runner = new ViteNodeRunner({\n  root: server.config.root,\n  base: server.config.base,\n  fetchModule(id) {\n    return node.fetchModule(id)\n  },\n  resolveId(id, importer) {\n    return node.resolveId(id, importer)\n  },\n})\n\nawait runner.executeFile('./index.ts')","lang":"typescript","description":"Demonstrates setting up vite-node programmatically: create Vite server, configure ViteNodeServer and ViteNodeRunner, install source map support, and execute a TypeScript file."},"warnings":[{"fix":"Ensure your Vite plugins are compatible with Vite v8. Update if necessary.","message":"v6.0.0 upgrades Vite from v5 to v8. The Vite plugin API and internal structures may have changed.","severity":"breaking","affected_versions":">=6.0.0"},{"fix":"Use ESM imports. If you were using CommonJS require(), switch to import or update your Node.js to support ESM.","message":"v5.0.0 migrated the codebase from the Vitest monorepo to a standalone repo. The package switched to ESM-only.","severity":"breaking","affected_versions":">=5.0.0"},{"fix":"For new projects, consider using Vite's environment API directly: https://vite.dev/guide/api-environment.html","message":"vite-node is effectively superseded by Vite's built-in Environment Module Runner. The maintainers recommend new projects use Vite's native solution.","severity":"deprecated","affected_versions":"*"},{"fix":"Always import from 'vite-node/client' or 'vite-node/server' as appropriate.","message":"The 'vite-node' main package entry exports no default; ViteNodeServer and ViteNodeRunner are in subpaths.","severity":"gotcha","affected_versions":"*"},{"fix":"Check Vite version and conditionally call buildStart if major version is less than 6.","message":"Older Vite versions (<6) require manually calling server.pluginContainer.buildStart({}) after createServer.","severity":"gotcha","affected_versions":"<6.0.0"}],"env_vars":null,"last_verified":"2026-04-25T00:00:00.000Z","next_check":"2026-07-24T00:00:00.000Z","problems":[{"fix":"Use ESM import: import { ViteNodeRunner } from 'vite-node/client'; or set \"type\": \"module\" in package.json.","cause":"Missing or incorrect import path when using CommonJS require.","error":"Error: Cannot find module 'vite-node/client'"},{"fix":"Use named exports from subpaths: import { ViteNodeServer } from 'vite-node/server'.","cause":"Trying to import default from 'vite-node' which has no default export.","error":"TypeError: viteNode.default is not a function"},{"fix":"Upgrade to vite-node v5+ or check that you are using the correct export name.","cause":"Using an older version of vite-node where the symbol was exported differently or was not yet available.","error":"SyntaxError: The requested module 'vite-node/client' does not provide an export named 'ViteNodeRunner'"},{"fix":"Ensure the module is installed and configured in Vite's resolve.alias or optimizeDeps.","cause":"Vite-node cannot resolve a dependency due to missing config or externalization issues.","error":"[vite-node] [Error] Failed to resolve module: some-module"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}