[!NOTE]
This project is firstly inspired by Nuxt 3's SSR implementation made by @pi0, as a PoC. Later, it made Vitest possible by providing the same pipeline as in Vite. It served the ecosystem well for a few years and later became a more generalized built-in solution as Vite Environment Module Runner. Vitest has migrated to the new official solution, which means has finished its mission. We will still keep it around for the ecosystem that built around it, but for new projects, please consider using the builtin Vite one instead.
Features
On-demand evaluation
Vite's pipeline, plugins, resolve, aliasing
Out-of-box ESM & TypeScript support
Respect vite.config.ts
Hot module replacement (HMR)
Separate server/client architecture
Top-level await
Shims for __dirname and __filename in ESM
Access to native node modules like fs, path, etc.
CLI Usage
Run JS/TS file on Node.js using Vite's resolvers and transformers.
npx vite-node index.ts
Options:
npx vite-node -h
Options via CLI
All ViteNodeServer options are supported by the CLI. They may be defined through the dot syntax, as shown below:
Now, you can run the file without passing it into Vite Node:
$ ./file.ts helloargv: [ 'hello' ]
Note that when using the --script option, Vite Node forwards every argument and option to the script to execute, even the one supported by Vite Node itself.
Programmatic Usage
In Vite Node, the server and runner (client) are separated, so you can integrate them in different contexts (workers, cross-process, or remote) if needed. The demo below shows a simple example of having both (server and runner) running in the same context
import { createServer, version as viteVersion } from 'vite'import { ViteNodeRunner } from 'vite-node/client'import { ViteNodeServer } from 'vite-node/server'import { installSourcemapsSupport } from 'vite-node/source-map'// create vite serverconst server = await createServer({ optimizeDeps: { // It's recommended to disable deps optimization noDiscovery: true, include: undefined, },})// For old Vite, this is needed to initialize the plugins.if (Number(viteVersion.split('.')[0]) < 6) { await server.pluginContainer.
Debugging
Debug Transformation
Sometimes you might want to inspect the transformed code to investigate issues. You can set environment variable VITE_NODE_DEBUG_DUMP=true to let vite-node write the transformed result of each module under .vite-node/dump.
If you want to debug by modifying the dumped code, you can change the value of VITE_NODE_DEBUG_DUMP to load and search for the dumped files and use them for executing.
VITE_NODE_DEBUG_DUMP=load vite-node example.ts
Or programmatically:
import { ViteNodeServer } from 'vite-node/server'const server = new ViteNodeServer(viteServer, { debug: { dumpModules: true, loadDumppedModules: true, },})
Debug Execution
If the process gets stuck, it might be because there are unresolvable circular dependencies. You can set VITE_NODE_DEBUG_RUNNER=true for vite-node to warn about this.
VITE_NODE_DEBUG_RUNNER=true vite-node example.ts
Or programmatically:
import { ViteNodeRunner } from 'vite-node/client'const runner = new ViteNodeRunner({ debug: true,})
Credits
Based on @pi0's brilliant idea of having a Vite server as the on-demand transforming service for Nuxt's Vite SSR.
Thanks @brillout for kindly sharing this package name.