# Migration Rules

This reference describes exactly what `vp migrate` does to a project: how it
updates dependencies, rewrites source imports and package scripts, and adjusts
package-manager configuration. See the [migration guide](./migrate.md) for the
command overview and workflow.

Except for [Before You Migrate](#before-you-migrate), which lists steps you
take yourself, everything below describes automatic behavior.

## Before You Migrate

1. Run `vp upgrade` so the global CLI has the latest migration rules. A stale
   local `vite-plus` is not a blocker: when the project's local copy is older,
   migration delegates to the global CLI.
2. Upgrade the project to Vite 8+ and Vitest 4.1+ when necessary.
3. Run `vp migrate` from the workspace root. Use `--no-interactive` in
   automated environments.
4. Review every changed manifest, package-manager config, source rewrite, and
   generated lockfile.
5. Validate with `vp install`, `vp check`, `vp test`, and `vp build`.

Migration is idempotent: running it again after a successful migration should
not produce another diff.

## Upgrade vs. Full Setup

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 and Prettier migration, framework shims, the tsconfig `baseUrl` fix,
  and the `.nvmrc`/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.

## Dependency Rules

What happens to each toolchain dependency, at a glance:

| Dependency                     | What happens                                                                                                                                                            |
| ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `vite-plus`                    | Added where the package is migrated; plain ranges re-pinned to the concrete target, directly or through a catalog.                                                      |
| `vite`                         | Existing declarations kept and pointed at the core alias. Under pnpm, added as a direct dev dependency wherever needed (see [Vite and Overrides](#vite-and-overrides)). |
| `vitest`                       | Removed in the common node-mode case because `vite-plus` provides it transitively. Kept or added only when [directly required](#when-vitest-is-directly-required).      |
| `@vitest/*`                    | Directly installed lockstep packages aligned to the bundled Vitest version (see [Vitest Ecosystem Packages](#vitest-ecosystem-packages)).                               |
| `@voidzero-dev/vite-plus-test` | Removed everywhere: dependencies, overrides, resolutions, and catalog aliases. Imports are rewritten to the current `vite-plus/test*` surface.                          |

### Version Selection

- `vite-plus` is pinned to the concrete version of the CLI running the
  migration, never the `latest` dist-tag.
- The `vite` alias targets `@voidzero-dev/vite-plus-core` from the same Vite+
  release.
- A catalog-backed manifest may contain `catalog:` or a named catalog
  reference. Migration keeps the reference and updates the referenced catalog
  value to the concrete toolchain target.
- Deliberate protocol pins are preserved: `workspace:`, `file:`, `link:`,
  `npm:`, `github:`, Git URLs, and HTTP URLs.
- Migration reconciles every workspace package, not only the root manifest.
  Shared overrides and catalogs stay at the workspace root; dependencies that
  provide a peer belong in each package that needs them.

### Vite and Overrides

Package-manager overrides do not create dependency edges by themselves. Under
pnpm, a package that lists `vite-plus` in `dependencies` or `devDependencies`
but has no `vite` entry anywhere (`dependencies`, `devDependencies`,
`optionalDependencies`, or `peerDependencies`) lets pnpm auto-install upstream
Vite to satisfy Vitest's required `vite` peer, splitting the project across
separate Vite+, Vite, and Vitest instances. To prevent this, `vp migrate` adds
the missing `vite` entry to `devDependencies` of every such package; the
workspace override then redirects it to Vite+ core.

Related rules:

- A direct `vite` declaration is never removed merely because a root override
  exists.
- Plain or stale aliases are normalized; named catalog references are kept.
- The direct-entry rule above is pnpm-specific. Bun mirrors its core alias as
  a direct dependency for its peer resolver, and npm browser-provider layouts
  may need a top-level `vite` edge so nested Vitest packages can resolve
  `vite`.

### When Vitest Is Directly Required

Migration keeps or adds a package-local `vitest` at the exact bundled version
when any of the following is true:

- an installed dependency has a non-optional `vitest` peer, whether exact or a
  range;
- the package uses Vitest browser mode or an opt-in browser provider;
- source or TypeScript configuration retains an upstream `vitest` reference;
- the package declares `@nuxt/test-utils`; or
- dependency metadata is unavailable and an existing direct `vitest` might be
  satisfying an unknown required peer.

Detection reads installed peer metadata, so integrations such as
`vite-plugin-gherkin` are handled even though their names do not contain
`vitest`.

When a package qualifies, migration:

- adds `vitest` to that package, not indiscriminately to every workspace
  package;
- uses the existing catalog reference when supported, otherwise the exact
  bundled version; and
- keeps a matching workspace override or resolution so the graph resolves a
  single Vitest version.

A peer declaration alone does not install Vitest. If a surviving
`peerDependencies.vitest` uses a catalog entry that migration will remove, it
is resolved to the public peer range first.

### Vitest Ecosystem Packages

Official current `@vitest/*` packages generally publish in lockstep with
Vitest. Migration aligns the ones the project directly installs, including
`@vitest/coverage-v8`, `@vitest/coverage-istanbul`, `@vitest/ui`, and
`@vitest/web-worker`:

- when the package manager supports catalogs, they are referenced through the
  toolchain catalog: an existing `catalog:` / `catalog:<name>` reference is
  preserved, a catalog entry is added for any package that lacks one, and each
  entry is updated to the bundled Vitest version;
- when catalogs are unsupported (npm, a standalone bun project, or a
  pre-catalog pnpm/Yarn), the concrete bundled version is written instead.

Packages that are **not** aligned:

- `@vitest/eslint-plugin` follows its own version line;
- `@vitest/coverage-c8` stopped at an older release and has no Vitest 4
  version; and
- third-party `vitest-*` integrations keep their own compatible versions,
  though their required Vitest peer may still trigger
  [direct provisioning](#when-vitest-is-directly-required).

For browser mode, the base `@vitest/browser` runtime and
`@vitest/browser-preview` are bundled by Vite+ and are removed as direct
dependencies. The Playwright and WebdriverIO providers stay opt-in: a kept or
injected provider is referenced through the preferred toolchain catalog at the
bundled Vitest version (or written concretely when catalogs are unsupported),
and its `playwright` or `webdriverio` peer is installed alongside.

Providers are detected before imports are rewritten. This covers legacy
projects that aliased `vitest` to `@voidzero-dev/vite-plus-test` and import
from `vitest/browser-<provider>`, `vitest/browser/providers/<provider>`, or
`vitest/plugins/browser-<provider>`: those imports still install the
corresponding `@vitest/browser-playwright` or `@vitest/browser-webdriverio`
dependency and its framework peer.

Object-valued nested npm and Bun overrides are preserved: they are
user-defined scopes rather than scalar version pins.

## Source Rewrite Rules

### `vite` Imports

`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.
- 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.

`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

- Ordinary `vitest` and `vitest/*` imports are rewritten to
  `vite-plus/test*`.
- Legacy Playwright and WebdriverIO provider imports are detected before this
  rewrite so their optional provider dependencies are not lost.
- Scoped `@vitest/browser*` imports are rewritten to the corresponding
  `vite-plus/test/browser*` exports, provisioning opt-in providers when
  needed.
- Existing `vite-plus/test*` imports are left unchanged.

### What Is Never Rewritten

- `declare module 'vitest'` and `declare module '@vitest/browser*'`: module
  augmentation must retain the upstream module identity.
- References that stay behind, such as `compilerOptions.types`,
  `require.resolve`, `import.meta.resolve`, and `vitest/package.json`,
  require package-local Vitest (see
  [When Vitest Is Directly Required](#when-vitest-is-directly-required)).
- In a package that declares `@nuxt/test-utils`, every `vitest` and
  `vitest/*` module specifier is preserved package-wide: the Nuxt transform
  requires the upstream identity and can otherwise inject a duplicate `vi`
  import. This exception does not apply to sibling packages or to scoped
  `@vitest/browser*` imports.

The `prefer-vite-plus-imports` lint rule follows the same Nuxt exception, so
lint autofix preserves these imports too.

## Package Script Rewrite Rules

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  |

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                                                    |
| ------------------------------------------------------- | -------------------------------------------------------- |
| `bunx --bun vite build`                                 | `bunx --bun vp build`                                    |
| `bunx --bun vitest run`                                 | `bunx --bun vp test run`                                 |
| `portless --tailscale run bunx --bun vite`              | `portless --tailscale run bunx --bun vp dev`             |
| `dotenv -e .env.test -- bunx --bun oxlint --type-aware` | `dotenv -e .env.test -- bunx --bun vp lint --type-aware` |

Unrelated `bunx` commands and other package-executor forms remain 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.

- `.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
  (`.github/actions/**/action.{yml,yaml}`) is repointed to `.node-version` so
  CI does not fail with "node version file ... does not exist".

## Package-Manager Rules

### pnpm

**Root settings location.** pnpm 10.6.2+ uses `pnpm-workspace.yaml` as the
single source for supported root settings. Migration moves recognized
`package.json#pnpm` fields there, including overrides, peer rules, patch
settings, package extensions, architecture and build policy, audit/update
configuration, and configuration dependencies. It removes the `pnpm` object
when it becomes empty and preserves unknown keys that may belong to other
tooling.

- When both files define the same migrated setting, object entries are merged
  recursively and unique array entries are retained. Values from
  `package.json#pnpm` win at conflicting scalar leaves, while workspace-only
  sibling entries are preserved.
- Before pnpm 10.6.2, these settings stay in `package.json#pnpm`. (Workspace
  settings support arrived incrementally: 10.5.0 in general, 10.5.1 for
  overrides, 10.6.2 for `peerDependencyRules`. pnpm 11 no longer reads the
  legacy `package.json` settings.)

**Catalogs.** Catalogs are a separate feature, supported from pnpm 9.5.0,
independent of the settings boundary above. Even below 10.6.2, where
overrides stay in `package.json#pnpm`, migration still rewrites the workspace
catalog off stale wrapper aliases and keeps `catalog:` overrides as
references rather than inlining them to concrete versions.

- Dependency references, default and named catalogs, overrides, and
  `peerDependencyRules` are kept consistent with each other.
- pnpm accepts the logical default catalog as either top-level `catalog` or
  `catalogs.default`, but not both. Migration preserves the existing form and
  never creates the other form beside it.
- When an existing named catalog already owns `vite-plus`, `vite`, or
  `vitest`, migration reuses that managed toolchain catalog for newly added
  dependencies and overrides. It creates a top-level default catalog only
  when no managed or default catalog can be reused.

**Other rules.**

- Each package that declares `vite-plus` also gets a direct `vite` dev
  dependency (see [Vite and Overrides](#vite-and-overrides)).
- Unrelated selector-shaped and object-valued overrides are preserved.

### npm

- Direct aliases are normalized before the matching override is added, so npm
  does not fail with `EOVERRIDE`.
- When a real Vite installation changes to the core alias, stale Vite install
  and lockfile state is removed before reinstalling.
- Opt-in browser-provider layouts get a top-level `vite` edge when nested
  Vitest packages otherwise cannot resolve it.

### Yarn

- Vite+ does not support Plug'n'Play. Migration detects explicit and implicit
  PnP and converts the project to `nodeLinker: node-modules`, preserving all
  unrelated `.yarnrc.yml` settings. `--no-interactive` accepts the
  conversion; a process-level `YARN_NODE_LINKER=pnp` must be fixed by the
  caller.
- Catalog references and user hoisting settings are preserved.
- Migration avoids split Vitest copies under workspace hoisting isolation: it
  applies a package-level fix where possible and warns when the isolation
  cannot be changed safely.

### Bun

- Bun catalogs only resolve inside a workspace (a root `package.json` with a
  non-empty `workspaces`). In a bun workspace, existing top-level or
  workspace catalog locations and named catalog references are preserved. A
  standalone (single-package) bun project keeps concrete specs and gets no
  catalog field, because `bun install` cannot resolve `catalog:` outside a
  workspace.
- The core alias is mirrored as a direct `vite` dependency so Bun sees the
  peer provider before applying overrides.

## After the Migration

- Each Vite config is inspected for Rolldown-incompatible patterns (such as
  `manualChunks`). Anything found is reported as a warning; the config is not
  changed.
- Dependencies are reinstalled once to refresh the lockfile. If installation
  fails, migration reports the error and exits with a nonzero status.
- After a successful migration, `vp fmt` runs on the files changed during
  migration, excluding paths that were already dirty in the Git worktree.
  Oxfmt selects the supported formats; non-Git projects retain full-project
  formatting. Formatting is skipped while the project still uses Prettier. A
  formatter failure is reported as a warning so the migration result and the
  manual formatting command remain available.
