vite-plus 1.4.0 → 1.5.0

package/docs/guide/migrate-rules.md

@@ -200,7 +200,7 @@ Object-valued nested npm and Bun overrides are preserved: they are user-defined
 
 `vite` and `vite/*` imports are rewritten to `vite-plus` **only in config entry files**: `vite.config.*`, `vitest.config.*`, and any config file the migration resolved. Every other file keeps its `vite` imports, for two reasons:
 
-- `vite-plus` is not a guaranteed superset of Vite's exposed surface. It owns only `defineConfig`, `defineProject`, and `lazyPlugins`, so rewriting a pass-through symbol such as `createBuilder` or `loadConfigFromFile` (including in `typeof import('vite')` type positions) can break.
+- `vite-plus` is not a guaranteed superset of Vite's exposed surface. It owns only `defineConfig`, `defineProject`, `lazyPlugins`, and `resolveConfigFromFile`, so rewriting a pass-through symbol such as `createBuilder` or `loadConfigFromFile` (including in `typeof import('vite')` type positions) can break.
 - An unrewritten `vite` import still resolves through the `@voidzero-dev/vite-plus-core` alias in a Vite+ project.
 
 Plugin packages (an unscoped name starting with `vite-plugin-` or `unplugin-`, or `vite` in `peerDependencies`/`dependencies`) skip the rewrite even in config files. Only the `vite` specifier is in scope for this rule.
@@ -250,18 +250,20 @@ The `prefer-vite-plus-imports` lint rule follows the same Nuxt exception, so lin
 
 Migration rewrites commands provided by the Vite+ toolchain in `package.json` scripts while preserving their arguments:
 
-| Before        | After                                       |
-| ------------- | ------------------------------------------- |
-| `vite`        | `vp dev`, or the matching `vp` subcommand   |
-| `vitest`      | `vp test`                                   |
-| `oxlint`      | `vp lint`                                   |
-| `oxfmt`       | `vp fmt`                                    |
-| `tsdown`      | `vp pack`                                   |
-| `lint-staged` | `vp staged`                                 |
-| `eslint`      | `vp lint`, when its optional migration runs |
-| `prettier`    | `vp fmt`, when its optional migration runs  |
-| `tsup`        | `vp pack`, when its optional migration runs |
-| `tsx`         | `vpx`, when its optional migration runs     |
+| Before        | After                                        |
+| ------------- | -------------------------------------------- |
+| `vite`        | `vp dev`, or the matching `vp` subcommand    |
+| `vitest`      | `vp test`                                    |
+| `oxlint`      | `vp lint`                                    |
+| `oxfmt`       | `vp fmt`                                     |
+| `tsdown`      | `vp pack`                                    |
+| `lint-staged` | `vp staged`                                  |
+| `eslint`      | `vp lint`, when its optional migration runs  |
+| `prettier`    | `vp fmt`, when its optional migration runs   |
+| `tsup`        | `vp pack`, when its optional migration runs  |
+| `tsx`         | `vpx`, when its optional migration runs      |
+| `oxnode`      | `vpx`, when its optional migration runs      |
+| `ts-node`     | `vpx`, for supported transpile-only commands |
 
 For commands launched through `bunx`, migration preserves `bunx` and its `--bun` flag (keeping the user's chosen runtime) and rewrites only the managed command. tsx is the exception: `bunx tsx` becomes `vpx`, and `bunx --bun tsx` keeps tsx (see [tsx to `vpx`](#tsx-to-vpx)). This also works when `bunx` follows a command-launcher delimiter such as `run` or `--`:
 
@@ -278,23 +280,80 @@ Unrelated `bunx` commands and other package-executor forms remain unchanged.
 
 When a `package.json` script, a lint-staged task, or a `#!/usr/bin/env tsx` shebang runs [tsx](https://tsx.is), migration offers to move it to [`vpx`](/guide/vpx), Vite+'s TypeScript script runner. It rewrites scripts and lint-staged tasks in `package.json` and JSON lint-staged files, and `#!/usr/bin/env tsx` shebangs in script files:
 
-| Before                                                                     | After                                      |
-| -------------------------------------------------------------------------- | ------------------------------------------ |
-| `tsx src/seed.ts --rows 10`                                                | `vpx src/seed.ts --rows 10`                |
-| `tsx watch --include "*.json" src/a.ts`                                    | `vpx --watch --include "*.json" src/a.ts`  |
-| `npx tsx a.ts`, `pnpm exec tsx a.ts`, `pnpm dlx tsx a.ts`, `bunx tsx a.ts` | `vpx a.ts`                                 |
-| `node --import tsx ./a.ts`                                                 | `vpx ./a.ts`                               |
-| `cross-env NODE_ENV=dev tsx a.ts`                                          | `cross-env NODE_ENV=dev vpx a.ts`          |
-| `concurrently "tsx watch a.ts" "vp dev"`                                   | `concurrently "vpx --watch a.ts" "vp dev"` |
+| Before                                                                     | After                                              |
+| -------------------------------------------------------------------------- | -------------------------------------------------- |
+| `tsx src/seed.ts --rows 10`                                                | `vpx src/seed.ts --rows 10`                        |
+| `tsx watch --include "*.json" src/a.ts`                                    | `vpx --watch --include "*.json" src/a.ts`          |
+| `npx tsx a.ts`, `pnpm exec tsx a.ts`, `pnpm dlx tsx a.ts`, `bunx tsx a.ts` | `vpx a.ts`                                         |
+| `node --import tsx ./a.ts`                                                 | `node --import vite-plus/register ./a.ts`          |
+| `node --import=tsx --test`                                                 | `node --import=vite-plus/register --test`          |
+| `NODE_OPTIONS='--import tsx' mocha`                                        | `NODE_OPTIONS='--import vite-plus/register' mocha` |
+| `cross-env NODE_ENV=dev tsx a.ts`                                          | `cross-env NODE_ENV=dev vpx a.ts`                  |
+| `concurrently "tsx watch a.ts" "vp dev"`                                   | `concurrently "vpx --watch a.ts" "vp dev"`         |
 
 `tsx watch` becomes `vpx --watch`, never `vpx watch`, which runs the npm package `watch`. Node.js options and tsx watch options keep their order, and `--no-cache` is dropped. A quoted command is rewritten only for programs that run it, such as `concurrently`, `nodemon --exec`, `sh -c`, and `cross-env-shell`; a quoted argument of other programs, as in `echo "tsx a.ts"`, is data. `vpx` needs the same Node.js versions as Vite+ itself, and migration already upgrades incompatible runtime pins to them (see [Vitest 5](/guide/vitest-v5)).
 
-Migration keeps tsx, with a warning, for a command `vpx` cannot run: `--eval`, `--print`, or `--check`, the REPL, `--test` without files or in watch mode, an entry without a file extension, commands that set `TSX_TSCONFIG_PATH` (pass `--tsconfig` to `vpx` instead) or load tsx through `NODE_OPTIONS`, and commands with pipes, variables, or subshells. It also reads the scripts a command runs, including local `--require` and `--import` modules, and keeps tsx when one does not exist yet, as when an earlier command generates it, and when `vpx` would fail on one: a `require()` of `./a.js` that only tsx resolves to `a.ts`, and, because tsx compiles ES module syntax to CommonJS, a `.cts` file with `import` or `export`, and a file that mixes `import` with `__dirname`, `__filename`, `require()`, or `module.exports` in a package without `"type": "module"`. This check skips globs and scripts after a `cd` or another shell state change, and reads only the files a command names, not the modules they import. It does not look for what else `vpx` handles differently, such as standard decorators, tsconfig `paths` in `require()`, or a tsconfig `module` of `node16` or `nodenext`; `vpx` reports those when the script runs. A package that lists tsx in `dependencies`, `optionalDependencies`, or `peerDependencies` keeps it too, since `vpx` comes from the `vite-plus` devDependency.
+The plain `node --import tsx` and `node --import=tsx` forms keep Node.js, its options, wrappers, and arguments. They use [`vite-plus/register`](/guide/vpx#using-nodejs-directly), so Node.js retains its eval, test discovery, and native watch behavior. Literal `NODE_OPTIONS` assignments also migrate, including assignments through `cross-env` and known command launchers. `vite-plus/register` accepts `TSX_TSCONFIG_PATH` as a fallback. Assignments that also load a legacy tsx hook, or reach a command that still needs tsx, stay unchanged.
+
+For the tsx executable and legacy loader forms such as `--loader tsx/esm` and `-r tsx/cjs`, migration keeps the existing `vpx` rules. It keeps tsx, with a warning, for `--eval`, `--print`, or `--check`, the REPL, `--test` without files or in watch mode, an entry without a file extension, or commands that load tsx through `NODE_OPTIONS`. Commands with pipes, variables, or subshells also stay unchanged. `vpx` accepts `TSX_TSCONFIG_PATH` as a fallback too; an explicit `--tsconfig` takes priority.
+
+Both migration paths read the scripts a command names, including local `--require` and `--import` modules. They keep tsx when a script does not exist yet, as when an earlier command generates it, or when the Vite+ loader would fail on it: a `require()` of `./a.js` that only tsx resolves to `a.ts`, a `.cts` file with `import` or `export`, or a file that mixes `import` with `__dirname`, `__filename`, `require()`, or `module.exports` in a package without `"type": "module"`. This check skips globs and scripts after a `cd` or another shell state change, and reads only the files a command names, not the modules they import. It does not look for other compiler differences, such as standard decorators, tsconfig `paths` in `require()`, or a tsconfig `module` of `node16` or `nodenext`; the loader reports those when the script runs. A package that lists tsx in `dependencies`, `optionalDependencies`, or `peerDependencies` keeps it too, since the replacement comes from the `vite-plus` devDependency.
 
 Migration removes the `tsx` devDependency only when nothing uses tsx anymore: no kept script, no import of `tsx` or its subpaths such as `tsx/esm/api` (in source, build output, or a `package.json` `imports` alias), no shebang, no tool setting such as `--import=tsx` in `package.json` or a JSON or JavaScript config, and no tsx command in CI workflows, git hooks, or shell scripts. The root's dependency stays while any workspace package still uses tsx, and a package's dependency stays while a nested package under it does. When tsx stays, the warning names what still uses it.
 
+Tool configurations and source files need manual edits. For example, change `nodeArguments: ['--import=tsx']` to `nodeArguments: ['--import=vite-plus/register']`, or Mocha's `"import": "tsx"` setting to `"import": "vite-plus/register"`. Keep tsx if the project uses its programmatic APIs.
+
 See [Coming from tsx](/guide/vpx#coming-from-tsx) for the other differences.
 
+### oxnode to `vpx`
+
+Migration offers to replace `oxnode`, the command from `@oxc-node/cli`, with `vpx`. It rewrites `package.json` scripts, lint-staged tasks in `package.json` and JSON files, and `#!/usr/bin/env oxnode` shebangs. Node.js preload shebangs such as `#!/usr/bin/env -S node --import @oxc-node/core/register` keep Node.js and use `vite-plus/register`, including in extensionless scripts. The migration preserves the shebang's `env` syntax, flags, and relative paths. On a project that already uses Vite+, run `vp migrate --full` to include this migration.
+
+| Before                                                    | After                                                |
+| --------------------------------------------------------- | ---------------------------------------------------- |
+| `oxnode ./scripts/seed.ts`                                | `vpx ./scripts/seed.ts`                              |
+| `oxnode -C dev ./build.ts`                                | `vpx -C dev ./build.ts`                              |
+| `oxnode watch --include "config/*.json" ./server.ts`      | `vpx --watch --include "config/*.json" ./server.ts`  |
+| `node --import @oxc-node/core/register ./scripts/seed.ts` | `node --import vite-plus/register ./scripts/seed.ts` |
+| `NODE_OPTIONS='--import @oxc-node/core/register' mocha`   | `NODE_OPTIONS='--import vite-plus/register' mocha`   |
+
+The `node --import @oxc-node/core/register` and `register.mjs` forms keep Node.js, its wrappers, arguments, and native watch, eval, and test modes. Literal `NODE_OPTIONS` assignments also use the public preload. Commands that use the `oxnode` executable follow the `vpx` rules instead: `oxnode --watch` stays unchanged because it starts Node.js's watcher, while `oxnode watch` and `vpx --watch` use oxc-node's watcher.
+
+Commands that explicitly set `OXC_TRANSFORM_ALL` to anything other than `typescript` stay unchanged. Nonempty `VP_SCRIPT_TSCONFIG` and `TSX_TSCONFIG_PATH` assignments also stay unchanged because they would change config selection. Commands that read an environment file stay unchanged because it can select a different transform mode. Migration checks the named script and local preloads for standalone oxc-node API usage, which would configure a different loader after migration; it does not follow their imports.
+
+Custom asynchronous `--loader` and `--experimental-loader` hooks stay in their original order when the register import changes. This supports project loaders for resolution and assets alongside the Vite+ TypeScript loader. It does not establish compatibility with a second TypeScript transformer or arbitrary synchronous `module.registerHooks()` chains.
+
+Direct `oxnode` commands and Node.js preload commands stay unchanged when an additional `--require` or `--import` can change loader settings. Node.js commands also stay unchanged when inline code still calls standalone oxc-node APIs. Migration checks explicit local shebang loaders relative to the owning package for standalone API references, without following their imports. It leaves the paths unchanged: at runtime, relative loader paths use the caller's working directory, not the script's directory.
+
+The `@oxc-node/cli` and `@oxc-node/core` development dependencies are removed only when no remaining use needs them. Loader references, API imports, CI commands, hooks, and shell scripts can keep these dependencies installed. Migration also checks files named by `--env-file` and `--env-file-if-exists`, regardless of their filename. If it cannot resolve or read an environment file, it keeps the dependencies for manual review. Runtime and peer dependencies stay in place.
+
+### ts-node to `vpx`
+
+Migration offers to replace supported ts-node commands with `vpx` only when type-checking is explicitly disabled. Plain `ts-node` type-checks before execution; `vpx` does not. Commands that still type-check stay unchanged with a warning, even when another option enables transpile-only mode.
+
+| Before                                                                            | After                                                               |
+| --------------------------------------------------------------------------------- | ------------------------------------------------------------------- |
+| `ts-node --transpileOnly ./scripts/seed.ts`                                       | `vpx ./scripts/seed.ts`                                             |
+| `ts-node -T -P tsconfig.scripts.json ./scripts/seed.ts`                           | `vpx --tsconfig=tsconfig.scripts.json ./scripts/seed.ts`            |
+| `ts-node-transpile-only ./scripts/seed.ts`                                        | `vpx ./scripts/seed.ts`                                             |
+| `node -r ts-node/register/transpile-only ./scripts/seed.ts`                       | `node --import vite-plus/register ./scripts/seed.ts`                |
+| `node --loader ts-node/esm/transpile-only ./scripts/seed.ts`                      | `node --import vite-plus/register ./scripts/seed.ts`                |
+| `NODE_OPTIONS='--require ts-node/register/transpile-only' node ./scripts/seed.ts` | `NODE_OPTIONS='--import vite-plus/register' node ./scripts/seed.ts` |
+
+The migration also reads `transpileOnly` and `typeCheck` from local JSONC tsconfig files, local `extends` chains, and literal `TS_NODE_TRANSPILE_ONLY` / `TS_NODE_TYPE_CHECK` assignments. `-P`, `--project`, and `TS_NODE_PROJECT` select the configuration. A directory passed to `-P` or `--project` resolves to its `tsconfig.json`; a directory in `TS_NODE_PROJECT` stays unchanged. When ts-node discovers a config implicitly, migration pins that file with `--tsconfig` so `vpx` uses it for the whole run. `ts-node-esm` and `--esm` are supported when type-checking is disabled.
+
+If an existing config and its local `extends` chain omit both `target` and `useDefineForClassFields`, the command stays unchanged with a warning. ts-node defaults to assignment semantics for class fields in this case, while `vpx` defaults to define semantics. Set `compilerOptions.useDefineForClassFields` to `false` to preserve assignment semantics before migrating.
+
+Supported Node.js preload commands keep Node.js and replace both the old loader option and module with `--import vite-plus/register`. Literal `NODE_OPTIONS` assignments also migrate when they reach a known `node` command and pass the same checks. An existing `TS_NODE_PROJECT` file selection stays in place. A preload that needs an implicit config pinned stays unchanged: set `TS_NODE_PROJECT` to the config file before migration, because Node.js cannot take `--tsconfig`.
+
+Preloads also stay unchanged when the working directory has no config but the entry file would discover a different one. Migration does not scan imported modules for additional config files.
+
+Custom compilers, transpilers, SWC, ts-node compiler overrides, unsupported configuration inheritance, eval, and REPL usage stay unchanged. Environment files, Node.js config files, additional preloads, and unsupported `NODE_OPTIONS` assignments also keep the original command because they can change ts-node settings before registration. Nonempty `VP_SCRIPT_TSCONFIG`, `TSX_TSCONFIG_PATH`, or `OXC_TSCONFIG_PATH` assignments stay unchanged because they would select a different config. Migration checks named scripts for known module incompatibilities; it does not follow their imports. Migrated scripts use the [tsconfig and module rules of `vpx`](/guide/vpx#tsconfig).
+
+Entries with static imports or re-exports of CommonJS values also stay unchanged. This includes named, namespace, and default bindings, `.js` files in CommonJS packages, and package entry points. Migration checks both import and require resolution without executing dependencies. Unresolved targets and targets that differ between these modes stay unchanged for manual review. Even `esModuleInterop: true` can unwrap a CommonJS `__esModule.default` value differently from Node.js, so that setting alone does not make a default import safe. Type-only imports and exports, imports used only for side effects, checked ES module targets, and named Node.js built-in bindings do not trigger this check.
+
+As with oxnode, migration rewrites package scripts, JSON lint-staged tasks, and supported env shebangs. Shebangs that need a pinned config stay unchanged because the config path depends on the caller's working directory. Existing Vite+ projects use `vp migrate --full`. The `ts-node` development dependency is removed only when no remaining command, loader, API import, or config reference needs it. Runtime and peer dependencies remain, and `typescript` is not removed.
+
 ## Continuous Integration Rules
 
 Migration replaces exact `voidzero-dev/setup-vp@v1` references in GitHub Actions workflows and composite actions under `.github` with the latest exact `setup-vp` release known to that Vite+ version. The frozen `v1` tag does not receive new releases. Existing exact versions and commit SHAs are left unchanged.

package/docs/guide/migrate.md

@@ -8,7 +8,7 @@ import { migrationPrompt, upgradePrompt } from '../.vitepress/theme/data/migrati
 
 ## Overview
 
-This command is the starting point for consolidating separate Vite, Vitest, Oxlint, Oxfmt, ESLint, Prettier, tsdown, tsup, and tsx setups into Vite+.
+This command is the starting point for consolidating separate Vite, Vitest, Oxlint, Oxfmt, ESLint, Prettier, tsdown, tsup, tsx, oxnode, and ts-node setups into Vite+.
 
 Use it when you want to take an existing project and move it onto the Vite+ defaults instead of wiring each tool by hand.
 
@@ -95,21 +95,21 @@ Upgrade the [global CLI](./upgrade.md#global-vp) to your target 1.0 release, the
 
 ### Without the Global CLI
 
-Use an existing Node.js runtime that satisfies `^22.18.0 || ^24.11.0 || >=26.0.0`. Run the target migrator through your package manager without adding it to the project first. For the `1.4.0` release:
+Use an existing Node.js runtime that satisfies `^22.18.0 || ^24.11.0 || >=26.0.0`. Run the target migrator through your package manager without adding it to the project first. For the `1.5.0` release:
 
 ::: code-group
 
 ```bash [pnpm]
-pnpm dlx --package=vite-plus@1.4.0 vp migrate --no-interactive
+pnpm dlx --package=vite-plus@1.5.0 vp migrate --no-interactive
 ```
 
 ```bash [npm]
-npx --package=vite-plus@1.4.0 vp migrate --no-interactive
+npx --package=vite-plus@1.5.0 vp migrate --no-interactive
 ```
 
 :::
 
-Replace `1.4.0` with your target release. For a preview, use the version from the PR and pass `--registry=https://registry-bridge.viteplus.dev` to `pnpm` or `npx` before the `vp` command. Keep the version in `--package` explicit so you run the target migrator rather than the old local CLI.
+Replace `1.5.0` with your target release. For a preview, use the version from the PR and pass `--registry=https://registry-bridge.viteplus.dev` to `pnpm` or `npx` before the `vp` command. Keep the version in `--package` explicit so you run the target migrator rather than the old local CLI.
 
 After migration, finish dependency installation and validate with the updated local CLI:
 
@@ -151,7 +151,7 @@ View and copy this prompt into your coding agent to upgrade an existing Vite+ 0.
 
 ### Vitest
 
-Vitest is automatically migrated through `vp migrate`. `vite-plus` re-exports upstream `vitest@5.0.5` under `vite-plus/test*`, so for node-mode tests a single `vite-plus` install is enough — you no longer need to install `vitest` directly.
+Vitest is automatically migrated through `vp migrate`. `vite-plus` re-exports upstream `vitest@5.1.0` under `vite-plus/test*`, so for node-mode tests a single `vite-plus` install is enough — you no longer need to install `vitest` directly.
 
 For browser mode, you can use the base browser runtime (`@vitest/browser`) and Preview provider (`@vitest/browser-preview`) included in `vite-plus`. To use Playwright or WebDriverIO, you also need the opt-in provider (`@vitest/browser-playwright` or `@vitest/browser-webdriverio`) and its framework peer (`playwright` or `webdriverio`).
 
@@ -234,11 +234,11 @@ export default defineConfig({
 });
 ```
 
-When no existing hook policy owns the workflow, `vp migrate` can move supported lint-staged rules and remove the old configuration and dependency. If an existing hook tool is preserved, keep lint-staged in place until you convert that hook policy manually. See the [Commit hooks guide](/guide/commit-hooks) and [Staged config reference](/config/staged) for details.
+When no existing hook policy owns the workflow, `vp migrate` can move supported lint-staged rules and remove the old configuration and dependency. If an existing hook tool is preserved, keep lint-staged in place until you convert that hook policy manually. See the [Commit Hooks](/guide/commit-hooks) and [Staged Config](/config/staged) for details.
 
 ### Git hook tools
 
-The `vp migrate` command does not automatically convert Husky setups. When Husky is detected, Vite+ leaves its hooks, lifecycle scripts, configuration, and dependencies unchanged and shows a warning. You can migrate the project manually using the [Commit hooks guide](/guide/commit-hooks).
+The `vp migrate` command does not automatically convert Husky setups. When Husky is detected, Vite+ leaves its hooks, lifecycle scripts, configuration, and dependencies unchanged and shows a warning. You can migrate the project manually using the [Commit Hooks](/guide/commit-hooks).
 
 Existing project-owned Vite+ hooks are also preserved. The default staged workflow is introduced only when no existing hook policy is found.
 
@@ -246,7 +246,7 @@ If your project currently uses `lefthook`, `simple-git-hooks`, or `yorkie`, `vp
 
 If you want to move one of those tools over to Vite+ manually, you can follow these steps. First, move your staged-file commands into the `staged` block within `vite.config.ts`. Then, update your lifecycle script so it runs `vp config`. You will also need to create a Vite+ hook at `.vite-hooks/pre-commit` that runs `vp staged`. Run `vp hooks enable` (or `vp config`) to install the dispatcher and set `core.hooksPath`. Finally, once you have confirmed that the Vite+ hook is working as expected, you can remove the old tool's configuration and dependency.
 
-Use `vp hooks status` to verify the dispatcher is active, and `vp hooks disable` if you need to turn it off again in this clone. You can find more details about the full Vite+ hook setup in the [Commit hooks guide](/guide/commit-hooks).
+Use `vp hooks status` to verify the dispatcher is active, and `vp hooks disable` if you need to turn it off again in this clone. You can find more details about the full Vite+ hook setup in the [Commit Hooks](/guide/commit-hooks).
 
 ## Examples
 

package/docs/guide/run.md

@@ -6,6 +6,10 @@
 `vpr` is available as a standalone shorthand for `vp run`. All examples below work with both `vp run` and `vpr`.
 :::
 
+::: info
+Vite Task parses simple commands and `&&` chains itself instead of passing them to a shell, so they behave the same on every platform. Other shell syntax, such as pipes or redirects, may behave differently across platforms.
+:::
+
 ## Overview
 
 Use `vp run` with existing `package.json` scripts:
@@ -232,7 +236,7 @@ vp run -w build
 
 ## Compound Commands
 
-Commands joined with `&&` are split into independent sub-tasks. Each sub-task is cached separately when [caching is enabled](/guide/cache#when-is-caching-enabled). This works for both `vite.config.ts` tasks and `package.json` scripts:
+Commands joined with `&&` are split into independent sub-tasks, unless they also use other shell syntax. Each sub-task is cached separately when [caching is enabled](/guide/cache#when-is-caching-enabled). This works for both `vite.config.ts` tasks and `package.json` scripts:
 
 ```json [package.json]
 {
@@ -266,6 +270,24 @@ $ vp build ○ cache miss: 'index.html' modified, executing
 vp run: 1/2 cache hit (50%), 2/2 successful, 120ms saved.
 ```
 
+### Environment Variable Prefixes
+
+Environment variable prefixes such as `FOO=bar command` work on every platform, without extra tools like `cross-env`:
+
+```json [package.json]
+{
+  "scripts": {
+    "build": "NODE_ENV=production node build.js"
+  }
+}
+```
+
+A prefix applies only to the command it directly precedes. In `FOO=1 a && b`, `FOO` is set for `a` but not for `b`.
+
+::: warning
+Prefixes may not work on every platform when the command also uses other shell syntax.
+:::
+
 ### Nested `vp run`
 
 When a command contains `vp run`, Vite Task inlines it as separate tasks instead of spawning a nested process. Each sub-task is cached independently and output stays flat:

package/docs/guide/test.md

@@ -2,7 +2,7 @@
 
 `vp test` runs tests with [Vitest](https://vitest.dev).
 
-Vite+ depends on Vitest `5.0.5`, which requires Node `^22.18.0 || ^24.11.0 || >=26.0.0`. For existing projects, follow [Upgrade to Vitest 5](./vitest-v5.md) before updating dependencies.
+Vite+ depends on Vitest `5.1.0`, which requires Node `^22.18.0 || ^24.11.0 || >=26.0.0`. For existing projects, follow [Upgrade to Vitest 5](./vitest-v5.md) before updating dependencies.
 
 `vp test` resolves Vitest from `vite-plus`'s dependencies first, then from your project.
 

package/docs/guide/troubleshooting.md

@@ -72,7 +72,7 @@ If `vp staged` fails or your pre-commit hook does not run:
 - if status shows `Preference: disabled (local)`, re-enable with `vp hooks enable`
 - check whether hooks were skipped intentionally through `VP_GIT_HOOKS=0`
 
-To stop hooks in this clone without deleting project policy files, run `vp hooks disable`. See the [Commit hooks guide](/guide/commit-hooks) for the full workflow.
+To stop hooks in this clone without deleting project policy files, run `vp hooks disable`. See the [Commit Hooks](/guide/commit-hooks) for the full workflow.
 
 A minimal staged config looks like this:
 

package/docs/guide/upgrade.md

@@ -1,6 +1,6 @@
 # Upgrading Vite+
 
-Use `vp upgrade` to update the global `vp` binary. To update the local `vite-plus` package in a project, see [Update Vite+](/guide/upgrade-project).
+Use `vp upgrade` to update the global `vp` binary, or [Homebrew](#homebrew) if it owns your installation. To update the local `vite-plus` package in a project, see [Update Vite+](/guide/upgrade-project).
 
 ## Overview
 
@@ -22,7 +22,7 @@ vp toolchain vite rolldown oxc
 vp toolchain --json
 ```
 
-The command uses the local `vite-plus` package when the project has one. Use `--global` to show the release for the global `vp` command:
+The command uses the local `vite-plus` package when the project has one. Use `--global` or `-g` to show the release for the global `vp` command:
 
 ```bash
 vp toolchain --global
@@ -87,15 +87,19 @@ Older versions are pruned automatically after each upgrade. The active version a
 
 ### Homebrew
 
-Homebrew owns its installed binary and JavaScript package. Update them with:
+The [official Homebrew tap](/guide/homebrew) owns its installed binary. Update it with:
 
 ```bash
-brew upgrade vite-plus
+brew upgrade voidzero-dev/vite-plus/vp
 ```
 
-`vp upgrade` detects Homebrew installations and directs you to this command without downloading or installing another version. This also applies to `--force`, a specific version, and `--rollback`. Use Homebrew to manage these installations.
+`vp upgrade` detects the installed formula and shows its Homebrew upgrade command without downloading or installing another version. This also applies to `--force`, a specific version, and `--rollback`. The script installer's rollback and automatic pruning do not apply to Homebrew installations.
 
-`vp upgrade --check` directs you to `brew outdated vite-plus`. Automatic npm update checks and notices are disabled for Homebrew installations.
+For the tap, run `vp` after upgrading to install the new version's dependencies in your user data directory. Setup preserves your management preferences.
+
+For the tap, `vp upgrade --check` directs you to `brew outdated voidzero-dev/vite-plus/vp`. Automatic npm update checks and notices are disabled for Homebrew installations.
+
+To switch to the tap, follow the [migration steps](/guide/homebrew#switch-an-existing-installation).
 
 ## Preview Builds
 
@@ -111,6 +115,8 @@ Preview builds are addressed by pull request number or commit SHA. They are not
 
 ### Global `vp` Preview
 
+For a Homebrew installation, follow the [tap preview instructions](/guide/homebrew#test-a-preview-build).
+
 Install a preview build of the global CLI by passing `VP_PR_VERSION` to the installer. Pass a pull request number or a commit SHA:
 
 ```bash

package/docs/guide/vitest-v5.md

@@ -1,6 +1,6 @@
 # Upgrade to Vitest 5
 
-Vite+ bundles Vitest `5.0.5`. Use Node `^22.18.0 || ^24.11.0 || >=26.0.0` for the CLI and tests.
+Vite+ bundles Vitest `5.1.0`. Use Node `^22.18.0 || ^24.11.0 || >=26.0.0` for the CLI and tests.
 
 ## Before you migrate
 
@@ -126,7 +126,7 @@ Review calls with benchmark options, imported or reassigned callbacks, callback
 
 ## Entry points and packages
 
-Use `vite-plus/test` for assertions and supported runner APIs. Keep coverage providers and `@vitest/ui` at the bundled runner's exact version, `5.0.5`. Keep `@vitest/web-worker` aligned when your project uses it.
+Use `vite-plus/test` for assertions and supported runner APIs. Keep coverage providers and `@vitest/ui` at the bundled runner's exact version, `5.1.0`. Keep `@vitest/web-worker` aligned when your project uses it.
 
 | v4 import                                | v5 import or action                                                         |
 | ---------------------------------------- | --------------------------------------------------------------------------- |

package/docs/guide/vpx.md

@@ -87,7 +87,7 @@ A missing path, or a missing name with a TypeScript extension, is an error: `vpx
 
 - `--tsconfig <path>` applies one tsconfig to every file (see [tsconfig](#tsconfig))
 - `--watch` runs the file again when a file it uses changes (see [Watch Mode](#watch-mode))
-- Node.js options before the file, such as `--inspect`, `--test`, `--env-file`, `--require`, and `--import`, are passed to Node.js; `--require` and `--import` preloads can be TypeScript too
+- Node.js options before the file, such as `--inspect`, `--test`, `--env-file`, `--require`, and `--import`, are passed to Node.js; modules loaded with `--require` and `--import` can be TypeScript too
 - Everything after the file, including `--`, is passed to the script
 
 ### Shebang Scripts
@@ -103,6 +103,38 @@ Scripts can use `vpx` as their interpreter. Make the file executable and keep it
 
 The `vpx` bin of the `vite-plus` package runs scripts on its own, so `"seed": "vpx ./scripts/seed.ts"` works in `package.json` scripts without the global CLI. It runs them on the Node.js that started it, which inside `vp run` and package manager scripts is the project's version.
 
+### Using Node.js Directly
+
+To run TypeScript with `node`, use `--import vite-plus/register`. This registers the Vite+ TypeScript loader before your script runs:
+
+```bash
+node --import=vite-plus/register ./scripts/seed.ts
+node --import vite-plus/register --test ./test/example.test.ts
+NODE_OPTIONS='--import=vite-plus/register' node ./scripts/seed.ts
+```
+
+Install `vite-plus` in the project first. Node.js resolves `vite-plus/register` from the project. The loader provides the same TypeScript transforms, tsconfig resolution, and source maps as `vpx`, and requires the same Node.js versions as Vite+.
+
+If a tool starts Node.js itself, add `--import vite-plus/register` to its Node.js arguments or `NODE_OPTIONS`. Replace an existing `--import tsx` argument with `--import vite-plus/register`. For example, an AVA configuration can use:
+
+```json
+{
+  "ava": {
+    "nodeArguments": ["--import=vite-plus/register"]
+  }
+}
+```
+
+Keep the tool's existing TypeScript file patterns and other settings. A JavaScript launcher can also run `await import('vite-plus/register')` before dynamically importing a TypeScript file. A static TypeScript import in that launcher is resolved before registration, so use `--import` for static imports.
+
+`fork()` and workers inherit the `--import` option through Node.js arguments. `NODE_OPTIONS` also passes the option to spawned Node.js processes. Replacing a child's arguments or environment follows Node.js's normal inheritance rules.
+
+To select a tsconfig, set `VP_SCRIPT_TSCONFIG=tsconfig.scripts.json`. The existing `TSX_TSCONFIG_PATH` variable also works, with `VP_SCRIPT_TSCONFIG` taking precedence. Otherwise the [usual tsconfig discovery](#tsconfig) applies. Each worker selects its config from its own environment, so workers can use different configs without changing their parent.
+
+Node.js owns its flags, test discovery, and native watch mode. Eval and stdin can import TypeScript files, but their input text is not transformed. Modules loaded with `--require` run before modules loaded with `--import`. To load a TypeScript setup file, put `--import ./setup.ts` after `--import vite-plus/register`. Repeated imports of `vite-plus/register` are harmless, including when a tool already runs under `vpx`.
+
+The [compiler differences from tsx](#coming-from-tsx) also apply when you use `vite-plus/register`.
+
 ### Watch Mode
 
 ```bash
@@ -132,7 +164,7 @@ It watches every file the script imports or requires (in worker threads too, on
 
 `vpx` reads compiler options from a tsconfig but does not type-check with it. Each file uses the nearest `tsconfig.json` above it that includes it through `files`, `include`, `exclude`, or project `references`, as `tsc` does, and `extends` is followed. Files in `node_modules` use no tsconfig, and neither does a file that no tsconfig includes, so it gets the defaults below. Such a file still resolves `paths` aliases through the nearest `tsconfig.json` above it, as tsx does: with a root tsconfig whose `include` is `["src"]`, a script in `scripts/` can import the same aliases as `src/`. Because the config depends on the file's location, not on the working directory, `vpx` compiles a file the same way wherever it runs from.
 
-`--tsconfig <path>` applies one config to every file instead, including files that config does not include. Without `--tsconfig`, an `OXC_TSCONFIG_PATH` or `TS_NODE_PROJECT` environment variable does the same. If it names a file that does not exist, or a tsconfig fails to parse, `vpx` prints a warning and runs without that config.
+`--tsconfig <path>` applies one config to every file instead, including files that config does not include. Without `--tsconfig`, `TSX_TSCONFIG_PATH`, `TS_NODE_PROJECT`, or `OXC_TSCONFIG_PATH` can select a config, in that order. If it names a file that does not exist, or a tsconfig fails to parse, `vpx` prints a warning and runs without that config.
 
 A file that no tsconfig applies to runs as if its `compilerOptions` were empty:
 
@@ -193,8 +225,16 @@ JSX that depends on a compiler plugin is not supported. `vpx` compiles JSX only
 - **Node.js version**: `vpx` needs Node.js `^22.18.0 || ^24.11.0 || >=26.0.0`, while tsx also runs on older releases.
 - **Watch mode**: `tsx watch` becomes `vpx --watch`, which takes tsx watch's options (see [Watch Mode](#watch-mode)). It also reruns the script on tsconfig edits and when a file a failed import looked for is created, which tsx watch misses.
 - **Eval, REPL, and `--check`**: `vpx --eval`, the REPL, and `vpx --check` do not transform TypeScript.
-- **`node --import tsx`**: `vpx` has no equivalent for tools that must start `node` themselves.
-- **Other loaders**: remove `--import tsx` from `NODE_OPTIONS`. Two loaders registered together compete for the same files.
+- **`node --import tsx`**: replace it with [`node --import vite-plus/register`](#using-nodejs-directly), including in tool settings and `NODE_OPTIONS`.
+- **Other loaders**: replace `--import tsx` with `--import vite-plus/register`. Registering both TypeScript loaders makes them compete for the same files.
+
+### Coming from oxnode
+
+`vp migrate` can replace `oxnode <file>` with `vpx <file>` and `oxnode watch <file>` with `vpx --watch <file>`. Both use oxc-node's transformer and watcher. Node.js commands and literal `NODE_OPTIONS` assignments that load `@oxc-node/core/register` use `vite-plus/register` instead. Migration removes the standalone development dependencies only when no remaining commands or imports need them. See [oxnode to `vpx`](/guide/migrate-rules#oxnode-to-vpx).
+
+### Coming from ts-node
+
+`vp migrate` can replace supported transpile-only ts-node commands with `vpx`. Supported Node.js preloads and literal `NODE_OPTIONS` assignments use `vite-plus/register`. Migration keeps commands that type-check because neither replacement performs that check. Custom compiler settings and remaining loader or API usage can also keep `ts-node` installed. See [ts-node to `vpx`](/guide/migrate-rules#ts-node-to-vpx).
 
 ## `vp exec`
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vite-plus",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "description": "The Unified Toolchain for the Web",
   "homepage": "https://viteplus.dev/guide",
   "bugs": {
@@ -32,7 +32,9 @@
     "templates"
   ],
   "type": "module",
-  "sideEffects": false,
+  "sideEffects": [
+    "./dist/register.js"
+  ],
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "exports": {
@@ -85,6 +87,10 @@
       "types": "./dist/oxlint-plugin.d.ts"
     },
     "./package.json": "./package.json",
+    "./register": {
+      "types": "./dist/register.d.ts",
+      "default": "./dist/register.js"
+    },
     "./pack": {
       "types": "./dist/pack.d.ts",
       "import": "./dist/pack.js"
@@ -339,53 +345,53 @@
     }
   },
   "dependencies": {
-    "@oxc-project/runtime": "=0.155.0",
-    "@oxc-project/types": "=0.155.0",
-    "@oxlint/plugins": "=1.89.0",
-    "@vitest/browser": "5.0.5",
-    "@vitest/browser-preview": "5.0.5",
-    "@vitest/mocker": "5.0.5",
-    "@vitest/pretty-format": "5.0.5",
-    "@vitest/snapshot": "5.0.5",
-    "@vitest/spy": "5.0.5",
-    "@vitest/utils": "5.0.5",
-    "oxfmt": "=0.74.0",
-    "oxlint": "=1.89.0",
-    "oxlint-tsgolint": "=7.0.2004",
-    "vite": "npm:@voidzero-dev/vite-plus-core@1.4.0",
-    "vitest": "5.0.5"
+    "@oxc-project/runtime": "=0.157.0",
+    "@oxc-project/types": "=0.157.0",
+    "@oxlint/plugins": "=1.91.0",
+    "@vitest/browser": "5.1.0",
+    "@vitest/browser-preview": "5.1.0",
+    "@vitest/mocker": "5.1.0",
+    "@vitest/pretty-format": "5.1.0",
+    "@vitest/snapshot": "5.1.0",
+    "@vitest/spy": "5.1.0",
+    "@vitest/utils": "5.1.0",
+    "oxfmt": "=0.76.0",
+    "oxlint": "=1.91.0",
+    "oxlint-tsgolint": "=7.0.2005",
+    "vite": "npm:@voidzero-dev/vite-plus-core@1.5.0",
+    "vitest": "5.1.0"
   },
   "devDependencies": {
-    "@emnapi/core": "2.0.0-alpha.5",
-    "@emnapi/runtime": "2.0.0-alpha.5",
+    "@emnapi/core": "2.0.0-beta.2",
+    "@emnapi/runtime": "2.0.0-beta.2",
     "@napi-rs/cli": "^3.10.0",
     "@nkzw/safe-word-list": "^3.1.0",
     "@types/cross-spawn": "^6.0.6",
     "@types/validate-npm-package-name": "^4.0.2",
-    "@vitest/browser-playwright": "5.0.5",
+    "@vitest/browser-playwright": "5.1.0",
     "@vitest/browser-webdriverio": "5.0.0",
-    "@voidzero-dev/vite-plus-prompts": "1.4.0",
+    "@voidzero-dev/vite-plus-prompts": "1.5.0",
     "@voidzero-dev/vite-task-client": "0.2.0",
     "bingo": "^0.13.2",
-    "cac": "^7.0.0",
+    "cac": "^7.1.0",
     "cross-spawn": "^7.0.5",
     "detect-indent": "^7.0.2",
     "detect-newline": "^4.0.1",
     "jsonc-parser": "^3.3.1",
     "lint-staged": "^17.6.0",
-    "minimatch": "^10.0.3",
+    "minimatch": "^11.0.0",
     "nanotar": "^0.3.0",
     "picocolors": "^1.1.1",
     "pirates": "^4.0.7",
     "tinyglobby": "^0.2.15",
-    "tsdown": "^0.23.1",
+    "tsdown": "^0.23.4",
     "validate-npm-package-name": "^8.0.0",
     "verkit": "^0.5.0",
     "yaml": "^2.9.1",
     "zod": "^4.4.3"
   },
   "peerDependencies": {
-    "@vitest/browser-playwright": "5.0.5",
+    "@vitest/browser-playwright": "5.1.0",
     "@vitest/browser-webdriverio": "^5.0.0-beta.5 || >=5.0.0",
     "playwright": "*"
   },
@@ -418,14 +424,14 @@
     "node": "^22.18.0 || ^24.11.0 || >=26.0.0"
   },
   "optionalDependencies": {
-    "@voidzero-dev/vite-plus-darwin-arm64": "1.4.0",
-    "@voidzero-dev/vite-plus-darwin-x64": "1.4.0",
-    "@voidzero-dev/vite-plus-linux-arm64-gnu": "1.4.0",
-    "@voidzero-dev/vite-plus-linux-arm64-musl": "1.4.0",
-    "@voidzero-dev/vite-plus-linux-x64-gnu": "1.4.0",
-    "@voidzero-dev/vite-plus-linux-x64-musl": "1.4.0",
-    "@voidzero-dev/vite-plus-win32-x64-msvc": "1.4.0",
-    "@voidzero-dev/vite-plus-win32-arm64-msvc": "1.4.0"
+    "@voidzero-dev/vite-plus-darwin-arm64": "1.5.0",
+    "@voidzero-dev/vite-plus-darwin-x64": "1.5.0",
+    "@voidzero-dev/vite-plus-linux-arm64-gnu": "1.5.0",
+    "@voidzero-dev/vite-plus-linux-arm64-musl": "1.5.0",
+    "@voidzero-dev/vite-plus-linux-x64-gnu": "1.5.0",
+    "@voidzero-dev/vite-plus-linux-x64-musl": "1.5.0",
+    "@voidzero-dev/vite-plus-win32-x64-msvc": "1.5.0",
+    "@voidzero-dev/vite-plus-win32-arm64-msvc": "1.5.0"
   },
   "scripts": {
     "build": "oxnode -C dev ./build.ts",