vite-plus 1.3.0 → 1.5.0

package/docs/guide/global-cli.md

@@ -71,6 +71,10 @@ irm https://vite.plus/ps1 | iex
 
 On Windows, you can instead download and run [`vp-setup.exe`](https://setup.viteplus.dev).
 
+For macOS and Linux, see the [Homebrew tap guide](/guide/homebrew) for installation instructions.
+
+The installer uses the Node.js version pinned in the Vite+ repository's [`.node-version`](https://github.com/voidzero-dev/vite-plus/blob/main/.node-version) to install its JavaScript dependencies. Each Vite+ release embeds this version at build time. Development and CI use the same file, which the dependency-upgrade workflow keeps up to date. CI integrations can select another compatible version through [`VP_SETUP_NODE_VERSION`](#vp-setup-node-version).
+
 After installation, open a new shell and run:
 
 ```bash
@@ -105,6 +109,47 @@ These variables control the installer scripts and the standalone Windows install
   $env:VP_VERSION = "1.2.3"; irm https://vite.plus/ps1 | iex
   ```
 
+#### `VP_SETUP_NODE_VERSION`
+
+- **Purpose**: Select the Node.js version used to install the global CLI's JavaScript dependencies. CI integrations such as [`setup-vp`](/guide/ci#node-js-during-installation) set this variable to reuse the project's runtime.
+- **Values**: An exact version, a version range, or an alias such as `22.23.1`, `22`, `^22.18.0`, `lts`, or `latest`. The installer resolves the value once to an exact version.
+- **Default**: Unset or empty (use the embedded Node.js default). Project files, `VP_NODE_VERSION`, session overrides, and the user-level default do not change this default.
+- **Compatibility**: The resolved version must meet the Node.js requirements of both the global CLI and its pinned `pnpm`. Otherwise, the installer uses the embedded default. An invalid or unresolvable value causes an error.
+- **Scope**: Initial dependency installation only. This variable does not set a project pin, session override, or global default. [`vp upgrade`](/guide/upgrade#global-vp) does not use this variable.
+
+#### `VP_SETUP_NODE_VERSION_FILE`
+
+- **Purpose**: Optional output file for integrations that need the exact version resolved from `VP_SETUP_NODE_VERSION`.
+- **Contents**: The resolved version, such as `22.23.1`, written after successful dependency installation. If compatibility requires the embedded default for installation, the file still contains the requested version's resolution.
+- **Default**: Unset (write no file). The installer also writes no file when `VP_SETUP_NODE_VERSION` is unset or empty, or when dependency installation is skipped.
+
+`setup-vp` manages this file automatically. Use its Node.js inputs to configure CI jobs.
+
+#### `VP_SETUP_SKIP_INSTALL_LOCKFILE`
+
+Set this variable to `1` to recover from a lockfile-related error during global CLI installation or `vp upgrade`. All other values, including unset or empty, keep the published installation lockfile enabled.
+
+The installer prints a warning and resolves dependencies without reading or recovering the installation lockfile. The requested CLI version stays pinned, but its dependency versions can differ from the release lockfile. Registry, authentication, and proxy settings remain in effect. This option does not affect project installations such as `vp install`.
+
+```bash
+# Retry installation without the bundled lockfile.
+curl -fsSL https://vite.plus | VP_SETUP_SKIP_INSTALL_LOCKFILE=1 bash
+
+# Or retry an upgrade, including the currently installed version.
+VP_SETUP_SKIP_INSTALL_LOCKFILE=1 vp upgrade --force
+```
+
+```powershell
+$env:VP_SETUP_SKIP_INSTALL_LOCKFILE = "1"
+try {
+  irm https://vite.plus/ps1 | iex
+} finally {
+  Remove-Item Env:VP_SETUP_SKIP_INSTALL_LOCKFILE
+}
+```
+
+Keep this override temporary. Later installations and upgrades use the published lockfile again when the variable is unset. To reinstall an affected version with its lockfile, unset the variable and run `vp upgrade <version> --force`.
+
 #### `VP_HOME`
 
 - **Purpose**: Optional pin for the single-root layout. Set it to an absolute path. Vite+ then puts bin, data, cache, config, and state under that directory. The installed CLI reads the same variable. See [Environment](/guide/env).
@@ -227,6 +272,7 @@ These variables configure the installed Vite+ CLI. `VP_HOME` (above) also applie
 
 - **Purpose**: Override Node.js version
 - **Default**: None (auto-detected)
+- **Scope**: Runtime commands. For the installer's dependency installation, use [`VP_SETUP_NODE_VERSION`](#vp-setup-node-version).
 - **Example**:
   ```bash
   # Run a command with a specific Node.js version
@@ -347,6 +393,14 @@ source ~/.config/vite-plus/env.nu
 
 For a custom `XDG_CONFIG_HOME`, use the absolute path to `<XDG_CONFIG_HOME>/vite-plus/env.nu` as resolved during installation. For an installation under `VP_HOME` or an existing `~/.vite-plus` installation, use `<VP_HOME>/env.nu` or `~/.vite-plus/env.nu` instead. Replace placeholders with actual paths and quote paths containing spaces. Open a new Nushell session and run `vp help` to verify the configuration.
 
+#### Nushell version
+
+Use Nushell 0.112.1 or later. In Nushell, a custom command or alias can have the same name as a built-in command, for example `def update []`. Nushell reads the Vite+ `env.nu` after your configuration. Thus, `env.nu` must call the built-in commands with the [`%` sigil](https://www.nushell.sh/lang-guide/chapters/custom_commands.html#calling-custom-commands), which Nushell 0.112.1 added.
+
+`vp env setup` checks the `nu` on `PATH`. With an earlier Nushell, it writes `env.nu` without the sigil. That `env.nu` still works, but a custom command with the name of a built-in command can stop Nushell at startup with `nu::parser::extra_positional` or a similar parse error. After you upgrade Nushell, run `vp env setup` again.
+
+If you have more than one Nushell installation, make sure that the `nu` on `PATH` during `vp env setup` is the Nushell that you start. A Nushell earlier than 0.112.1 cannot parse an `env.nu` that `vp env setup` wrote for a later version.
+
 #### `CI`
 
 - **Purpose**: Indicates running in CI environment
@@ -374,7 +428,7 @@ For example, `VP_VERSION=1.0.0 vp-setup.exe --version 2.0.0` installs version 2.
 
 ### Homebrew
 
-For a Homebrew installation, the first `vp` command sets up your shell, shims, and environment-management preferences. It reuses Homebrew's binary and bundled JavaScript. Setup stores its completion state in your user directories and does not need write access to the Homebrew prefix.
+The [official Homebrew tap](/guide/homebrew) installs the native CLI. The first `vp` command installs matching JavaScript dependencies in your data directory and sets up your shell, shims, and environment-management preferences. Setup stores its state in your directories without writing to the Homebrew prefix.
 
 Later commands reuse that setup while the installed binary remains unchanged. Generated shims follow Homebrew's public `vp` entrypoint when Homebrew replaces a version. Setup preserves your saved management preferences during this replacement.
 
@@ -384,11 +438,13 @@ To prefer your existing Node.js and package managers during the first run, use:
 VP_NODE_MANAGER=no VP_PM_MANAGER=no vp help
 ```
 
-After setup, use `vp env off` to change this preference. Commands that need missing runtimes or project dependencies can still download them.
+After setup, use `vp env off` to change this preference. The tap still prepares its pinned Node.js and pnpm to install CLI dependencies. Commands that need missing runtimes or project dependencies can also download them.
 
 Use Homebrew to [upgrade](/guide/upgrade#homebrew) or [remove](/guide/implode#homebrew) its package.
 
-`vp env doctor` identifies the Homebrew installation and its binary path. It checks the `vp` command and the user shim directory on `PATH` separately. If only the shim directory is missing, follow its shell setup instructions to enable the shims.
+`vp env doctor` identifies the Homebrew source, formula name, and binary path. It checks the `vp` command and the user shim directory on `PATH` separately. If only the shim directory is missing, follow its shell setup instructions to enable the shims.
+
+See the [official tap guide](/guide/homebrew) for registry configuration and migration instructions.
 
 ## Use It Without a Local Package
 

package/docs/guide/homebrew.md

@@ -0,0 +1,127 @@
+# Homebrew tap
+
+The official tap supports macOS and glibc Linux on ARM64 and x64. Homebrew manages the native `vp` executable; `vp` manages its JavaScript dependencies, downloaded Node.js versions, package managers, and settings in your user directories.
+Stable installation downloads the executable and its dependency lockfile from GitHub Releases. This step needs no existing Node.js or package manager installation, or npm registry access.
+
+## Install
+
+Install the tap:
+
+```bash
+brew tap voidzero-dev/vite-plus https://github.com/voidzero-dev/vite-plus
+brew install voidzero-dev/vite-plus/vp
+vp
+```
+
+The explicit repository URL is required because the formula is part of the Vite+ repository.
+If you already use Vite+, follow the [migration steps](#switch-an-existing-installation).
+
+## First use
+
+On first use, `vp` installs its matching CLI dependencies and configures your shell and tool-management preferences. This step needs access to Node.js downloads and your npm registry.
+Setup uses the release's pinned Node.js and pnpm versions, even if you choose to prefer system tools. A compatible [`VP_SETUP_NODE_VERSION`](/guide/global-cli#vp-setup-node-version) can override the installation runtime without changing Node.js selection for your projects.
+`vp` stores dependencies in `<DATA>/cli-packages/<version>/<platform>`.
+`<DATA>` comes from the [Vite+ directory configuration](/guide/global-cli#installation-variables).
+
+Open a new terminal after setup so the shims are available on `PATH`. Later invocations reuse the completed setup.
+Use [`vp env on` and `vp env off`](/guide/env) to change which tools `vp` manages.
+
+## Custom npm registry
+
+First-run setup reads `~/.npmrc`, including npm-compatible authentication:
+
+```ini
+registry=https://registry.example.com/repository/npm/
+//registry.example.com/repository/npm/:_authToken=${NPM_TOKEN}
+```
+
+Export `NPM_TOKEN` before running `vp`. The native pnpm downloader and pnpm dependency installation both use this configuration.
+You can select another file with `NPM_CONFIG_USERCONFIG` or override the registry with `NPM_CONFIG_REGISTRY`.
+Relative user-config paths resolve from your current directory. No Homebrew-specific npm variables are required.
+
+Authentication failures stop setup. Fix the configuration and run `vp` again; setup preserves your management choices.
+
+## Recover from failed setup
+
+Run `vp env doctor` to inspect the executable, dependency directory, and shims. Its CLI dependency check reads local files and does not install or repair dependencies. Other checks can fetch Node.js version metadata.
+
+Fix the reported configuration, access, or disk-space problem, then run `vp --help` to retry setup.
+For a lockfile error, the [installer recovery option](/guide/global-cli#vp-setup-skip-install-lockfile) also works with Homebrew:
+
+```bash
+VP_SETUP_SKIP_INSTALL_LOCKFILE=1 vp --help
+```
+
+This resolves dependencies without the published lockfile. A later invocation without the override restores the normal lockfile checks and can reinstall those dependencies.
+If pnpm fails, the reported log contains its exit code and recognized error codes, without raw package-manager output.
+Configured tool shims can run cached Node.js, package managers, and global packages independently of CLI dependency repair.
+
+## Switch an existing installation
+
+Keep your existing directory settings. Migration preserves your preferences, runtimes, and global packages, and updates their shims to Homebrew's public `vp` command.
+Do not run `vp implode`: it removes that user data. Open a new terminal after switching.
+
+### Switch from the script installer
+
+Run the `brew tap` and `brew install` commands above. Then invoke Homebrew's executable directly, so an existing script-install shim cannot take precedence:
+
+```bash
+"$(brew --prefix)/bin/vp" env setup --refresh
+```
+
+### Switch from Homebrew Core
+
+The `vite-plus` formula provides the same commands and must be removed before installing the tap:
+
+```bash
+brew tap voidzero-dev/vite-plus https://github.com/voidzero-dev/vite-plus
+brew uninstall vite-plus
+brew install voidzero-dev/vite-plus/vp
+"$(brew --prefix)/bin/vp" env setup --refresh
+```
+
+## Upgrade or remove
+
+```bash
+brew upgrade voidzero-dev/vite-plus/vp
+```
+
+Run `vp` after upgrading to prepare its matching dependencies. Setup preserves your preferences.
+`vp upgrade` identifies the official tap and directs you to `brew upgrade voidzero-dev/vite-plus/vp`.
+
+For complete removal, remove your user data before uninstalling the executable:
+
+```bash
+vp implode
+brew uninstall voidzero-dev/vite-plus/vp
+```
+
+`brew uninstall` alone keeps user data. On a shared machine, each operating-system account can remove its own data with `vp implode` before the executable is removed.
+
+## Test a preview build
+
+Set `HOMEBREW_VP_PR_VERSION` to a PR number or full commit SHA. The PR must have a published `preview-build` that includes Homebrew tap support. Use a full SHA to keep installation and verification on the same commit:
+
+```bash
+brew tap voidzero-dev/vite-plus https://github.com/voidzero-dev/vite-plus
+HOMEBREW_VP_PR_VERSION="<full-commit-sha>" brew install voidzero-dev/vite-plus/vp
+HOMEBREW_VP_PR_VERSION="<full-commit-sha>" brew test voidzero-dev/vite-plus/vp
+```
+
+Use `brew reinstall` instead of `brew install` to replace an installed tap build. If the `vite-plus` formula is installed, run `brew uninstall vite-plus` first; this keeps your user data.
+`brew test` uses temporary user data and does not change your shell configuration. Run `vp` afterward to set up the preview for your account. If switching from the script installer, [refresh its shims](#switch-from-the-script-installer) to use the Homebrew executable.
+
+Homebrew downloads only the native preview package from the registry bridge and verifies its checksum. It resolves PR numbers to the latest published commit, which can differ from the current PR head.
+First launch installs the matching dependencies from the bridge. An explicit `NPM_CONFIG_REGISTRY` must point to a registry that also serves those preview packages.
+
+The selector is specific to this tap. It does not change other Homebrew formulae, and no npm client is needed during `brew install`.
+To test changes to the formula itself, first check out the PR in the tap repository. Set `HOMEBREW_NO_AUTO_UPDATE=1` for these commands to keep that checkout.
+
+To return to a stable release, clear the overrides, restore the tap's `main` branch if you changed its checkout, and update it before reinstalling:
+
+```bash
+unset HOMEBREW_VP_PR_VERSION HOMEBREW_NO_AUTO_UPDATE
+git -C "$(brew --repository voidzero-dev/vite-plus)" switch main
+brew update
+brew reinstall voidzero-dev/vite-plus/vp
+```

package/docs/guide/ide-integration.md

@@ -63,9 +63,7 @@ You can also manually set up the Zed config:
       "initialization_options": {
         "settings": {
           "run": "onType",
-          "fixKind": "safe_fix",
-          "typeAware": true,
-          "unusedDisableDirectives": "deny"
+          "fixKind": "safe_fix"
         }
       }
     },

package/docs/guide/implode.md

@@ -26,13 +26,15 @@ vp implode --yes
 
 ## Homebrew
 
-Run `vp implode` first to remove Vite+-managed runtimes, global packages, configuration, shims, and shell entries. Then remove the Homebrew package:
+For the [official Homebrew tap](/guide/homebrew), run `vp implode` first to remove Vite+-managed runtimes, global packages, configuration, shims, and shell entries. Then remove the Homebrew package:
 
 ```bash
 vp implode
-brew uninstall vite-plus
+brew uninstall voidzero-dev/vite-plus/vp
 ```
 
-The confirmation prompt explains that the Homebrew package will remain installed. After cleanup, `vp implode` directs you to `brew uninstall vite-plus`.
+The confirmation prompt explains that the Homebrew package will remain installed. After cleanup, `vp implode` shows the uninstall command for the owning formula.
+
+To keep your data when switching installations, follow the [migration steps](/guide/homebrew#switch-an-existing-installation) instead of running `vp implode`.
 
 Restart your terminal before you run `vp` again. In Bash, you can run `hash -r` instead to clear cached command paths. If the Homebrew package is still installed, the next `vp` command starts first-run setup again.

package/docs/guide/local-cli.md

@@ -87,6 +87,27 @@ overrides:
 
 :::
 
+::: warning Existing direct dependencies with npm
+If your npm project already lists `vite` in `dependencies` or `devDependencies`, change that entry to the same alias as `overrides.vite`. npm requires a direct dependency and its override to use the [same dependency specification](https://docs.npmjs.com/cli/v11/configuring-npm/package-json/#overrides). Otherwise, `npm install` fails with `EOVERRIDE`.
+
+For example, update an existing `vite` development dependency as follows. Keep the other dependencies in your manifest:
+
+```json [package.json]
+{
+  "devDependencies": {
+    "vite": "npm:@voidzero-dev/vite-plus-core@<vite-plus-version>",
+    "vite-plus": "<vite-plus-version>"
+  },
+  "overrides": {
+    "vite": "npm:@voidzero-dev/vite-plus-core@<vite-plus-version>",
+    "vitest": "<vitest-version>"
+  }
+}
+```
+
+If you also declare `vitest` directly, set its dependency entry to the exact version in `overrides.vitest`. Run `npm install` after these changes to update the lockfile and installed dependencies.
+:::
+
 ::: details Why are these settings needed?
 
 Dependencies and plugins can import `vite` or `vitest` directly, even when your own code imports from `vite-plus`. These overrides align their dependencies with the toolchain Vite+ uses:

package/docs/guide/migrate-rules.md

@@ -18,11 +18,31 @@ Migration is idempotent: running it again after a successful migration should no
 
 On a project that already depends on `vite-plus`, `vp migrate` performs an upgrade only: it updates dependencies and package-manager configuration and finalizes imports. It does not touch project setup.
 
-- `--full` also runs the setup actions: git hooks, editor config, agent files, ESLint, Prettier, and tsup migration, framework shims, the tsconfig `baseUrl` fix, and the `.nvmrc`/Volta to `.node-version` conversion.
+- `--full` also runs the setup actions: git hooks, editor config, agent files, ESLint, Prettier, tsup, and tsx migration, framework shims, the tsconfig `baseUrl` fix, and the Volta to `.node-version` conversion.
 - `--hooks`, `--agent`, and `--editor` opt into a single setup action without `--full`.
 
 When a default upgrade skips setup actions that would apply, it prints a hint to run `vp migrate --full`. Fresh (non Vite+) projects always run the full migration.
 
+## Oxlint JSON Inheritance
+
+When `.oxlintrc.json` or `.oxlintrc.jsonc` uses `extends`, `vp migrate` resolves each file path relative to the config that declares it. It creates shared TypeScript configs and imports them through `lint.extends`, including nested inheritance. Oxlint applies the existing merge order, rule severities, and overrides. Plain `vp lint` uses the migrated rules without a `-c` flag.
+
+Migration assumes ESM projects. Shared configs become sibling `.ts` files. Imports from JavaScript and TypeScript configs use `.js` specifiers, which Vite and TypeScript resolve to the generated source files without changing compiler settings. File-level TypeScript pragmas stay before generated imports. Workspace consumers reuse the same generated modules, including the workspace that owns a shared config. Migration defaults stay in each workspace's local `lint` block. Edit these TypeScript files to update shared settings. Original shared JSON and JSONC files remain available to other consumers; edits to those originals do not update the migrated configs.
+
+JS-plugin declarations stay in their original config or override. Relative plugin paths become absolute paths at runtime through `fileURLToPath(new URL(..., import.meta.url))`. Explicit inherited `typeAware` and `typeCheck` settings take precedence over migration defaults.
+
+Cleanup removes each completed workspace symlink independently. Shared aliases that remain on disk keep their targets and dependencies available.
+
+A shared config's owner keeps `env`, `globals`, `settings`, and `ignorePatterns` at the top level of its `lint` block through references to the shared module. Edits to these fields apply to the owner. Other consumers do not inherit them.
+
+Generated modules include a source marker. A later migration attempt reuses these modules without replacing user edits, so a preserved consumer can migrate after its conflict is resolved. Existing modules without a matching marker remain conflicts.
+
+Failed merges and existing `lint` blocks record a pending marker in the Vite config, so an isolated failure can be retried after the conflict is resolved. A successful merge removes this marker. Completed workspace merges record a completion marker, including configs merged inline. After fixing an unreadable config, run `vp migrate` again to migrate the remaining consumers and remove JSON files that are no longer needed.
+
+Shared config imports use literal paths so Vite and TypeScript can resolve filenames containing `#` or `%`. A relative import path containing `?` or a literal backslash requires a manual migration: Vite treats `?` as a query delimiter, and TypeScript treats backslashes as path separators. Migration preserves the JSON config and reports a warning in these cases.
+
+Missing files, invalid JSON, inheritance cycles, conflicting output files, and package-local plugins that resolve differently from the Vite config directory produce a warning and leave the original config in place. Configs outside the project or workspace, configs inside `node_modules`, CommonJS Vite configs, and an existing `lint` block require a manual merge. Workspace JSON removal waits until all migration outcomes are known. Preserved JSON consumers retain their transitive dependencies, including configs whose owners migrated successfully. If an inheritance graph cannot be read, workspace JSON files are kept and their owners use shared modules, because the unreadable consumer can reference them. `vp lint` continues to reject string paths in `lint.extends`; path resolution happens only during migration.
+
 ## Pack Configuration
 
 `vp migrate` updates static `pack` objects in `vite.config.*` and exported objects in `tsdown.config.*` for [tsdown 0.23](https://github.com/rolldown/tsdown/releases/tag/v0.23.0). This also runs on existing Vite+ projects without `--full`, including workspace packages. Arrays and direct objects returned by `defineConfig` callbacks are supported. JSON tsdown configs receive the same updates after they merge into `vite.config.ts`.
@@ -180,11 +200,13 @@ 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.
 
+`vite/rolldown` and `vite/rolldown/*` are never rewritten, because `vite-plus` does not export those subpaths; they keep resolving through the core alias.
+
 `declare module 'vite'` augmentations follow the same rule and are preserved outside config files. Through the core alias they reach the same `@voidzero-dev/vite-plus-core` module whose `UserConfig` types `defineConfig` from `vite-plus`, so they keep working after migration; `vite-plus` itself exports no `UserConfig` symbol, so a rewritten `declare module 'vite-plus'` augmentation would merge with nothing. Extensions aimed at `vite-plus`'s own surface are written against `vite-plus` by hand.
 
 ### `vitest` and Browser Imports
@@ -228,19 +250,22 @@ 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 |
-
-For commands launched through `bunx`, migration preserves `bunx` and its `--bun` flag (keeping the user's chosen runtime) and rewrites only the managed command. This also works when `bunx` follows a command-launcher delimiter such as `run` or `--`:
+| 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 `--`:
 
 | Before                                                  | After                                                    |
 | ------------------------------------------------------- | -------------------------------------------------------- |
@@ -251,16 +276,93 @@ For commands launched through `bunx`, migration preserves `bunx` and its `--bun`
 
 Unrelated `bunx` commands and other package-executor forms remain unchanged.
 
+### tsx to `vpx`
+
+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`                                                 | `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)).
+
+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.
 
 ## Node.js Version Rules
 
-Migration converts legacy Node.js version-manager files to `.node-version`, the format Vite+ reads. On an existing Vite+ project this conversion is part of the full setup bucket, so it runs with `vp migrate --full`; fresh migrations run it unconditionally.
+Migration converts the Volta `volta.node` pin to `.node-version`, because Vite+ does not read Volta. On an existing Vite+ project this conversion is part of the full setup bucket, so it runs with `vp migrate --full`; fresh migrations run it unconditionally.
 
-- `.nvmrc` and Volta `volta.node` pins are converted to `.node-version`. An existing `.node-version` is kept.
-- When `.nvmrc` is removed, any `actions/setup-node` `node-version-file: .nvmrc` reference in `.github/workflows/*.{yml,yaml}` and composite actions under `.github` (`.github/**/action.{yml,yaml}`) is repointed to `.node-version` so CI does not fail with "node version file ... does not exist".
+- When `.node-version` or `.nvmrc` exists, migration keeps it and skips the Volta conversion. Vite+ reads both files directly (see [Node.js Selection](/guide/env#node-js-selection)).
 
 ## Package-Manager Rules
 

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, and tsup 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.3.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.3.0 vp migrate --no-interactive
+pnpm dlx --package=vite-plus@1.5.0 vp migrate --no-interactive
 ```
 
 ```bash [npm]
-npx --package=vite-plus@1.3.0 vp migrate --no-interactive
+npx --package=vite-plus@1.5.0 vp migrate --no-interactive
 ```
 
 :::
 
-Replace `1.3.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/package-management.md

@@ -212,7 +212,7 @@ Use these when you need lower-level package-manager behavior.
   - **Patching**: `patch`, `patch-commit`
   - **Packaging and publishing**: `pack`, `version`, `publish`, `stage`, `dist-tag`, `deprecate`
   - **Inspection**: `view`, `search`, `licenses`, `audit`, `fund`, `ping`
-  - **Authentication and access**: `login`, `logout`, `whoami`, `token`, `owner`
+  - **Authentication and access**: `login`, `logout`, `whoami`, `token`, `owner`, `team`
   - **Configuration**: `config`, `cache`
   - **Package manifest**: `pkg get`, `pkg set`, `pkg delete`, `pkg fix`
 

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: