You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Vite as Node runtime.<br>The engine that powers <ahref="https://github.com/nuxt/nuxt">Nuxt 3 Dev SSR</a> and <i><ahref="https://github.com/vitest-dev/vitest/pull/8208">used to</a></i> power <ahref="https://github.com/vitest-dev/vitest">Vitest</a>.
> This project is firstly inspired by [Nuxt 3's SSR](https://antfu.me/posts/dev-ssr-on-nuxt) implementation made by [@pi0](https://github.com/pi0), as a PoC. Later, it made [Vitest](https://github.com/vitest-dev/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](https://vite.dev/guide/api-environment.html). Vitest has [migrated to the new official solution](https://github.com/vitest-dev/vitest/pull/8208), 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.
8
18
9
-
Vite as Node runtime.
19
+
## Features
10
20
11
-
> **EXPERIMENTAL**
21
+
- On-demand evaluation
22
+
- Vite's pipeline, plugins, resolve, aliasing
23
+
- Out-of-box ESM & TypeScript support
24
+
- Respect `vite.config.ts`
25
+
- Hot module replacement (HMR)
26
+
- Separate server/client architecture
27
+
- Top-level `await`
28
+
- Shims for `__dirname` and `__filename` in ESM
29
+
- Access to native node modules like `fs`, `path`, etc.
12
30
31
+
## CLI Usage
13
32
14
-
## Usage
33
+
Run JS/TS file on Node.js using Vite's resolvers and transformers.
15
34
16
35
```bash
17
36
npx vite-node index.ts
@@ -23,29 +42,141 @@ Options:
23
42
npx vite-node -h
24
43
```
25
44
26
-
##Features
45
+
### Options via CLI
27
46
28
-
- Out-of-box ESM & TypeScript support (possible for more with plugins)
29
-
- Top-level await
30
-
- Vite plugins, resolve, aliasing
31
-
- Respect `vite.config.ts`
32
-
- Shims for `__dirname` and `__filename` in ESM
33
-
- Access to native node modules like `fs`, `path`, etc.
34
-
- Watch mode (like `nodemon`)
47
+
[All `ViteNodeServer` options](https://github.com/antfu-collective/vite-node/blob/main/src/types.ts#L92-L111) are supported by the CLI. They may be defined through the dot syntax, as shown below:
Note that for options supporting RegExps, strings passed to the CLI must start _and_ end with a `/`;
37
54
38
-
- Production, yet - in very early stage, check it later
39
-
- Most of the time, when other tools can do that job
40
-
- We need to start a Vite server upon each execution, which inevitably introduces some overhead. Only use it when you want the same behavior as Vite or the powerful plugins system (for example, testing components with a Vite-specific setup).
55
+
### Hashbang
41
56
42
-
## Why?
57
+
If you prefer to write scripts that don't need to be passed into Vite Node, you can declare it in the [hashbang](https://bash.cyberciti.biz/guide/Shebang).
43
58
44
-
It runs Vite's id resolving, module transforming, and most importantly, the powerful plugins system!
59
+
Simply add `#!/usr/bin/env vite-node --script` at the top of your file:
45
60
46
-
## How?
61
+
_file.ts_
62
+
63
+
```ts
64
+
#!/usr/bin/envvite-node--script
65
+
66
+
console.log('argv:', process.argv.slice(2))
67
+
```
47
68
48
-
It fires up a Vite dev server, transforms the requests, and runs them in Node.
69
+
And make the file executable:
70
+
71
+
```sh
72
+
chmod +x ./file.ts
73
+
```
74
+
75
+
Now, you can run the file without passing it into Vite Node:
76
+
77
+
```sh
78
+
$ ./file.ts hello
79
+
argv: [ 'hello' ]
80
+
```
81
+
82
+
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.
83
+
84
+
## Programmatic Usage
85
+
86
+
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
// For old Vite, this is needed to initialize the plugins.
104
+
if (Number(viteVersion.split('.')[0]) <6) {
105
+
awaitserver.pluginContainer.buildStart({})
106
+
}
107
+
108
+
// create vite-node server
109
+
const node =newViteNodeServer(server)
110
+
111
+
// fixes stacktraces in Errors
112
+
installSourcemapsSupport({
113
+
getSourceMap: source=>node.getSourceMap(source),
114
+
})
115
+
116
+
// create vite-node runner
117
+
const runner =newViteNodeRunner({
118
+
root: server.config.root,
119
+
base: server.config.base,
120
+
// when having the server and runner in a different context,
121
+
// you will need to handle the communication between them
122
+
// and pass to this function
123
+
fetchModule(id) {
124
+
returnnode.fetchModule(id)
125
+
},
126
+
resolveId(id, importer) {
127
+
returnnode.resolveId(id, importer)
128
+
},
129
+
})
130
+
131
+
// execute the file
132
+
awaitrunner.executeFile('./example.ts')
133
+
134
+
// close the vite server
135
+
awaitserver.close()
136
+
```
137
+
138
+
## Debugging
139
+
140
+
### Debug Transformation
141
+
142
+
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`.
143
+
144
+
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.
145
+
146
+
```bash
147
+
VITE_NODE_DEBUG_DUMP=load vite-node example.ts
148
+
```
149
+
150
+
Or programmatically:
151
+
152
+
```js
153
+
import { ViteNodeServer } from'vite-node/server'
154
+
155
+
constserver=newViteNodeServer(viteServer, {
156
+
debug: {
157
+
dumpModules:true,
158
+
loadDumppedModules:true,
159
+
},
160
+
})
161
+
```
162
+
163
+
### Debug Execution
164
+
165
+
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.
166
+
167
+
```bash
168
+
VITE_NODE_DEBUG_RUNNER=true vite-node example.ts
169
+
```
170
+
171
+
Or programmatically:
172
+
173
+
```js
174
+
import { ViteNodeRunner } from'vite-node/client'
175
+
176
+
construnner=newViteNodeRunner({
177
+
debug:true,
178
+
})
179
+
```
49
180
50
181
## Credits
51
182
@@ -64,5 +195,3 @@ Thanks [@brillout](https://github.com/brillout) for kindly sharing this package
0 commit comments