vite-node

vite-node

Vite as Node runtime.
The engine that powers Nuxt 3 Dev SSR and used to power Vitest.

[!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 vite-node 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:

npx vite-node --options.deps.inline="module-name" --options.deps.external="/module-regexp/" index.ts

Note that for options supporting RegExps, strings passed to the CLI must start and end with a /;

Hashbang

If you prefer to write scripts that don't need to be passed into Vite Node, you can declare it in the hashbang.

Simply add #!/usr/bin/env vite-node --script at the top of your file:

file.ts

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

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

And make the file executable:

chmod +x ./file.ts

Now, you can run the file without passing it into Vite Node:

$ ./file.ts hello
argv: [ '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 server
const 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.buildStart({})
}

// create vite-node server
const node = new ViteNodeServer(server)

// fixes stacktraces in Errors
installSourcemapsSupport({
  getSourceMap: source => node.getSourceMap(source),
})

// create vite-node runner
const runner = new ViteNodeRunner({
  root: server.config.root,
  base: server.config.base,
  // when having the server and runner in a different context,
  // you will need to handle the communication between them
  // and pass to this function
  fetchModule(id) {
    return node.fetchModule(id)
  },
  resolveId(id, importer) {
    return node.resolveId(id, importer)
  },
})

// execute the file
await runner.executeFile('./example.ts')

// close the vite server
await server.close()

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.

Sponsors

License

MIT License © 2021 Anthony Fu

Similar packages

Other packages similar to vite-node

ts-node

ts-node is a TypeScript execution engine and REPL for Node.js. It allows you to run TypeScript files directly in Node.js without pre-compiling them. Unlike vite-node, ts-node does not provide HMR and is not integrated with Vite's ecosystem.

esbuild-runner

esbuild-runner enables you to run scripts using ESBuild, which is a fast JavaScript bundler and minifier. It provides fast compilation but does not offer HMR or the same level of integration with Vite's development server and features.

babel-node

babel-node is part of the Babel toolchain and allows you to run Node.js scripts with Babel's support for the latest JavaScript syntax. It is similar to vite-node in that it supports modern JavaScript features, but it does not have built-in HMR or the optimizations provided by Vite.