vite-plus 0.3.3 → 1.0.0-rc.1

package/docs/guide/install.md

@@ -39,7 +39,7 @@ A range resolves to an already-downloaded satisfying version when possible, othe
 
 Vite+ currently downloads the declared package manager (the `onFail: "download"` behavior); the other `onFail` values are accepted but not yet differentiated.
 
-The explicit `packageManager` field (or the `devEngines.packageManager` declaration) also affects matching package-manager shims. If a project has `packageManager: "npm@10.9.4"`, `npm` and `npx` use npm 10.9.4. Other generated alias pairs behave the same way: `pnpm`/`pnpx`, `yarn`/`yarnpkg`, and `bun`/`bunx`. Mismatched tools are not translated; `npm` in a `pnpm` project still resolves as npm.
+The explicit `packageManager` field (or the `devEngines.packageManager` declaration) also affects matching package-manager shims. If a project has `packageManager: "npm@10.9.4"`, `npm` and `npx` use npm 10.9.4. Other generated aliases behave the same way: `pnpm`/`pnpx`/`pn`/`pnx`, `yarn`/`yarnpkg`, and `bun`/`bunx`. Mismatched tools are not translated; `npm` in a `pnpm` project still resolves as npm.
 
 ## Usage
 

package/docs/guide/lint.md

@@ -20,7 +20,11 @@ vp lint --type-aware
 
 Put lint configuration directly in the `lint` block in the root `vite.config.ts` so all your configuration stays in one place. We do not recommend using `oxlint.config.ts` or `.oxlintrc.json` with Vite+.
 
-Vite+ does not currently support nested lint configuration. For now, use [`lint.overrides`](/guide/monorepo#root-config-with-overrides) in the root `vite.config.ts` for file- or package-specific rules. The long-term behavior is open for discussion; [share your use case and expectations](/guide/troubleshooting#nested-lint-or-format-config-is-not-applied) to help shape it.
+`vp lint` finds its config from the working directory, so package directories without their own `lint` block use the root config. Relative file arguments retain their meaning. Use [`lint.overrides`](/guide/monorepo#root-config-with-overrides) for file- or package-specific rules instead of adding `lint` blocks to package configs.
+
+`vp check` uses the workspace-root `lint` block when it exists, including from a package directory. Package configs cannot replace those lint settings in `vp check`.
+
+An explicit `vp lint -c <path>` or `vp lint --config <path>` selects another config. Otherwise, Oxlint discovers the nearest `vite.config.*` file with a `lint` block. Supported extensions are `.js`, `.mjs`, `.ts`, `.cjs`, `.mts`, and `.cts`. Nested configs do not override settings for individual files.
 
 For the upstream rule set, options, and compatibility details, see the [Oxlint docs](https://oxc.rs/docs/guide/usage/linter.html).
 

package/docs/guide/local-cli.md

@@ -52,20 +52,20 @@ You need to add overrides to your package manager so that other packages resolve
 ```yaml [pnpm-workspace.yaml]
 overrides:
   vite: npm:@voidzero-dev/vite-plus-core@latest
-  vitest: 4.1.11
+  vitest: 5.0.1
 ```
 
 ```json [npm / Bun package.json]
 "overrides": {
   "vite": "npm:@voidzero-dev/vite-plus-core@latest",
-  "vitest": "4.1.11"
+  "vitest": "5.0.1"
 }
 ```
 
 ```json [Yarn package.json]
 "resolutions": {
   "vite": "npm:@voidzero-dev/vite-plus-core@latest",
-  "vitest": "4.1.11"
+  "vitest": "5.0.1"
 }
 ```
 

package/docs/guide/migrate-rules.md

@@ -44,23 +44,67 @@ When a default upgrade skips setup actions that would apply, it prints a hint to
 
 Migration preserves the previous defaults by setting `deps.resolveDepSubpath` to `true` when absent. Enabled ATTW checks receive `profile: 'strict'` when no profile is set. Explicit values, including `false`, remain unchanged.
 
+The inserted settings include comments with documentation links and instructions for adopting the new defaults. Remove `deps.resolveDepSubpath: true` to [preserve external subpath imports as written](https://tsdown.dev/options/dependencies#deps-resolvedepsubpath). Remove the inserted `attw.profile: 'strict'` to use the new `esm-only` [resolution profile](https://tsdown.dev/options/lint#profiles). This skips `node10` and CommonJS resolution checks. Keep either setting if your package requires the previous behavior. Migration does not add these comments to explicit settings.
+
 `noExternal` moves to `deps.alwaysBundle`, preserving matcher expressions, references, and callback methods. Existing `deps.alwaysBundle` values remain unchanged.
 
 When `external` accompanies either `skipNodeModulesBundle` form, static matchers and references to local constants move to `inputOptions.external` before `deps.neverBundle` is set. Constant declarations and references stay intact. This preserves the original matching rules, including external file paths. Unsupported matchers, conflicting `inputOptions`, and declaration-specific dependency rules leave the pack object unchanged and produce a manual-migration warning.
 
 The transform does not evaluate configuration code. Objects with spreads, computed keys, or duplicate keys, and conflicting old and new options require manual review. Dynamic boolean selectors remain unchanged. Unrelated Vite and plugin options remain unchanged. Run `vp pack` after migration to check the result. Node.js requirements, TypeScript module resolution, and programmatic `build()` return values require separate review.
 
+## Task Cache Configuration
+
+`vp migrate` moves `env`, `untrackedEnv`, `input`, and `output` from the top level of each task into the task's [`cache`](/config/run#cache) object. It updates static `run.tasks` objects in `vite.config.*`. This also runs on existing Vite+ projects without `--full`, including workspace packages.
+
+| Previous task config | Updated task config                            |
+| -------------------- | ---------------------------------------------- |
+| No `cache`           | Adds `cache` with the moved settings           |
+| `cache: true`        | Replaces `true` with the moved settings        |
+| `cache: { ... }`     | Adds the moved settings to the existing object |
+
+```ts
+// Before
+build: {
+  command: 'vp build',
+  env: ['NODE_ENV'],
+  input: [{ auto: true }, '!dist/**'],
+},
+
+// After
+build: {
+  command: 'vp build',
+  cache: {
+    env: ['NODE_ENV'],
+    input: [{ auto: true }, '!dist/**'],
+  },
+},
+```
+
+Moved settings keep their text and indentation, and the formatting step described in [After the Migration](#after-the-migration) indents them inside `cache`. Comments on their own line above a moved setting, and `//` comments that follow it on the same line, move with it.
+
+The transform does not evaluate configuration code. It leaves a task unchanged and prints a manual-migration warning when the task has:
+
+- spreads, or computed, escaped, or duplicate keys;
+- a moved setting written as a method, such as `input() { ... }`;
+- a comment between a moved setting and its comma, or after the last setting in `cache`;
+- a moved setting that already exists in `cache`;
+- a `cache` value other than `true` or an object literal.
+
+It also warns about tasks in a `vite.config.*` object that is not the exported config itself, such as a variable the config refers to or an object passed to `mergeConfig`. Tasks created in other modules, for example by a shared helper function, are not detected. Move their settings by hand; `vp run` lists every task that still needs it.
+
+With `cache: false`, the moved settings would have no effect, so decide whether to remove them or enable caching. On a project that is otherwise up to date, `vp migrate` prints these warnings without running the rest of the 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.                          |
+| 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. pnpm packages that use only `vite-plus` need no new `vite` entry (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
 
@@ -72,14 +116,14 @@ What happens to each toolchain dependency, at a glance:
 
 ### 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.
+You can use `vite-plus` in a pnpm package without declaring `vite`. The `vite-plus` package includes a `vite` dependency aliased to its core, which provides Vitest's required peer. Migration keeps the workspace override for other Vite consumers but does not add `vite` to a package solely because it uses `vite-plus`.
 
 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.
 - Under pnpm the managed override keys use an explicit `@*` range (`vite@*`, `vitest@*`). pnpm applies an override by replacing the declared spec on every manifest, importer manifests included. A bare key matches any spec, including `catalog:`, and `vp up` then rewrites that reference to a concrete version. The `@*` range keeps the override on the semver ranges that transitive and peer declarations use. It leaves `catalog:` references to the catalog, which already resolves them to Vite+ core. Migration re-keys a project that still holds the bare key, and keeps its named-catalog choice.
-- 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`.
+- 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
 
@@ -114,9 +158,11 @@ Packages that are **not** aligned:
 - `@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.
+For browser mode, Vite+ bundles the base `@vitest/browser` runtime and `@vitest/browser-preview`; migration removes their direct dependency entries. The Playwright provider stays opt-in. Migration uses the bundled Vitest version for `@vitest/browser-playwright`, through the preferred toolchain catalog or the dependency entry, and installs its `playwright` peer alongside.
+
+Migration detects Playwright usage before it rewrites imports, including legacy `vitest/browser-playwright`, `vitest/browser/providers/playwright`, and `vitest/plugins/browser-playwright` aliases.
 
-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.
+`vp migrate` restores removed Vite+ WebDriverIO aliases to `@vitest/browser-webdriverio` and adds `^5.0.0` if the provider is missing. It upgrades older versions, narrows ranges that allow versions below `5.0.0`, updates referenced catalog entries, and removes overrides that force an older provider. Versions and ranges that meet the minimum stay unchanged. Migration ensures the required `webdriverio` peer and adds an `@vitest/browser` override matching bundled Vitest (`resolutions` for Yarn). You manage later community provider upgrades. See [Community WebDriverIO provider](./vitest-v5.md#community-webdriverio-provider).
 
 Object-valued nested npm and Bun overrides are preserved: they are user-defined scopes rather than scalar version pins.
 
@@ -225,7 +271,7 @@ Migration converts legacy Node.js version-manager files to `.node-version`, the
 
 **Other rules.**
 
-- Each package that declares `vite-plus` also gets a direct `vite` dev dependency (see [Vite and Overrides](#vite-and-overrides)).
+- Packages that use `vite-plus` without a direct `vite` declaration keep that layout (see [Vite and Overrides](#vite-and-overrides)).
 - Unrelated selector-shaped and object-valued overrides are preserved.
 
 ### npm

package/docs/guide/migrate.md

@@ -1,10 +1,14 @@
+<script setup lang="ts">
+import { migrationPrompt, upgradePrompt } from '../.vitepress/theme/data/migration-prompts.ts';
+</script>
+
 # Migrate to Vite+
 
 `vp migrate` helps move existing projects onto Vite+.
 
 ## Overview
 
-This command is the starting point for consolidating separate Vite, Vitest, Oxlint, Oxfmt, ESLint, Prettier, and tsup setups into Vite+.
+This command is the starting point for consolidating separate Vite, Vitest, Oxlint, Oxfmt, ESLint, Prettier, tsdown, and tsup 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.
 
@@ -55,11 +59,13 @@ See [Migration Rules](./migrate-rules.md) for the exact dependency, source rewri
 
 Most projects will require further manual adjustments after running `vp migrate`.
 
+For the Vitest v5 upgrade, read the [compatibility settings and review checklist](./vitest-v5.md) and the [upstream Vitest migration guide](https://vitest.dev/guide/migration/). The preflight checks your original runner version and Node runtime before dependency updates. Keep the original lockfile available and resolve blocking findings before retrying.
+
 ## Recommended Workflow
 
 Before running the migration:
 
-- Upgrade to Vite 8+ and Vitest 4.1+ first
+- For projects that do not use Vite+ yet, upgrade to Vite 8+ and Vitest 4.1+ first
 - Make sure you understand any existing lint, format, or test setup that should be preserved
 
 After running the migration:
@@ -71,38 +77,87 @@ After running the migration:
 
 ## Migration Prompt
 
-If you want to hand this work to a coding agent (or the reader is a coding agent!), use this migration prompt:
+View and copy this prompt into your coding agent to migrate an existing project to Vite+:
+
+<CopyPrompt :prompt="migrationPrompt" label="View Migration Prompt" />
+
+## Upgrade from Vite+ 0.3 to 1.0
+
+Vite+ 1.0 includes the breaking changes in Vitest 5. Read the [Vite+ compatibility guide](./vitest-v5.md) alongside the [upstream migration guide](https://vitest.dev/guide/migration/).
+
+Library builds also use tsdown 0.23. Review the [pack configuration migration rules](./migrate-rules.md#pack-configuration) and [upstream release notes](https://github.com/rolldown/tsdown/releases/tag/v0.23.0) for option changes and new defaults.
+
+Keep your project's original dependencies and lockfile until migration identifies the old runner. Updating the project dependencies first can prevent the migration from preserving v4 behavior. Use one of the following paths from the workspace root.
+
+### With the Global CLI
 
-```md
-Migrate this project to Vite+. Vite+ replaces the current split tooling around runtime management, package management, dev/build/test commands, linting, formatting, and packaging. Run `vp help` to understand Vite+ capabilities and `vp help migrate` before making changes. Use `vp migrate --no-interactive` in the workspace root. Make sure the project is using Vite 8+ and Vitest 4.1+ before migrating.
+Upgrade the [global CLI](./upgrade.md#global-vp) to your target 1.0 release, then run `vp migrate --no-interactive`. For a preview, follow the [preview installation instructions](./upgrade.md#global-vp-preview).
 
-After the migration:
+### Without the Global CLI
 
-- Confirm `vite` imports were rewritten to `vite-plus` where needed
-- Confirm `vitest` imports were rewritten to `vite-plus/test` (and `@vitest/browser*` to `vite-plus/test/browser*`) where needed
-- On pnpm, keep the `vite`, `vitest` dependency entries configured by `vp migrate` so the workspace aliases and overrides stay effective; with other package managers, you can remove them once those rewrites are confirmed
-- Move remaining tool-specific config into the appropriate blocks in `vite.config.ts`
+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.0.0-rc.1` release:
 
-Command mapping to keep in mind:
+::: code-group
 
-- `vp run <script>` is the equivalent of `pnpm run <script>`
-- `vp dev` and `vp test` always run the built-ins; `vp run dev` and `vp run test` run the `dev` and `test` scripts from `package.json`
-- `vp install`, `vp add`, and `vp remove` delegate through the package manager declared by `packageManager`
-- `vp dev`, `vp build`, `vp preview`, `vp lint`, `vp fmt`, `vp check`, and `vp pack` replace the corresponding standalone tools
-- Prefer `vp check` for validation loops
+```bash [pnpm]
+pnpm dlx --package=vite-plus@1.0.0-rc.1 vp migrate --no-interactive
+```
+
+```bash [npm]
+npx --package=vite-plus@1.0.0-rc.1 vp migrate --no-interactive
+```
+
+:::
 
-Finally, verify the migration by running: `vp install`, `vp check`, `vp test`, and `vp build`
+Replace `1.0.0-rc.1` 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:
+
+::: code-group
+
+```bash [pnpm]
+pnpm install
+pnpm exec vp check
+pnpm exec vp test
+pnpm exec vp build
+```
 
-Summarize the migration at the end and report any manual follow-up still required.
+```bash [npm]
+npm install
+npm exec -- vp check
+npm exec -- vp test
+npm exec -- vp build
 ```
 
+:::
+
+Use `vp pack` in place of `vp build` for a library that uses the pack command. Run configured browser, coverage, and benchmark suites as well.
+
+### Review the Upgrade
+
+On an existing Vite+ project, use the default upgrade flow. Add `--full` if you also want to repeat project setup. Resolve blockers and review the file-specific report before committing. See [Upgrade vs. Full Setup](./migrate-rules.md#upgrade-vs-full-setup) for the scope of each mode.
+
+After the migrated project passes validation, [check whether you can remove the generated v4 compatibility settings](./vitest-v5.md#remove-unneeded-compatibility-settings) with no code changes or small, localized fixes. Keep compatibility for now if removal requires extensive test changes or you cannot validate the result.
+
+For libraries, review the generated [tsdown compatibility settings](#tsdown) after a successful `vp pack` run. Follow their documentation links before adopting the new defaults, and check the emitted imports and declarations with your package's consumers.
+
+### Copy Prompt
+
+View and copy this prompt into your coding agent to upgrade an existing Vite+ 0.3 project:
+
+<CopyPrompt :prompt="upgradePrompt" label="View Upgrade Prompt" />
+
 ## Tool-Specific Migrations
 
 ### Vitest
 
-Vitest is automatically migrated through `vp migrate`. `vite-plus` re-exports upstream `vitest@4.x` 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.0.1` 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`).
 
-Browser mode is more nuanced. `vite-plus` bundles the base browser runtime (`@vitest/browser`) and the preview provider (`@vitest/browser-preview`), but the **Playwright** and **WebdriverIO** providers stay opt-in: `@vitest/browser-playwright` (with its `playwright` peer) and `@vitest/browser-webdriverio` (with its `webdriverio` peer) are **not** shipped with `vite-plus`, so non-browser projects never pull them in. `vp migrate` detects the provider you actually use and adds it — pinned to the bundled vitest version — together with its framework. If you migrate manually and use one of these providers, install the provider package and its framework yourself so `vite-plus/test/browser-playwright` / `vite-plus/test/browser-webdriverio` can resolve.
+`vp migrate` adds the Playwright provider at the bundled Vitest version and ensures its framework peer. You can import it from `vite-plus/test/browser-playwright`.
+
+For WebDriverIO, import from the community-maintained `@vitest/browser-webdriverio`. Migration restores legacy Vite+ provider imports, ensures a provider version of at least `5.0.0`, and adds an `@vitest/browser` override that matches the bundled runner. Manage later provider upgrades and framework peers yourself. See [Community WebDriverIO provider](./vitest-v5.md#community-webdriverio-provider).
 
 If you are migrating manually, update all the imports to `vite-plus/test*` instead:
 
@@ -126,6 +181,17 @@ const { page } = await import('vite-plus/test/browser/context');
 
 ### tsdown
 
+`vp migrate` updates supported static options in `pack` blocks and `tsdown.config.*` for tsdown 0.23. This also runs for existing Vite+ projects and workspace packages without `--full`. See [Pack Configuration](./migrate-rules.md#pack-configuration) for the option mappings and cases that require manual review.
+
+The transform preserves earlier defaults by inserting `deps.resolveDepSubpath: true` and, when ATTW checks are enabled, `attw.profile: 'strict'` if these settings are absent. Each inserted setting includes a `tsdown <0.23 compatibility` comment with a documentation link and removal guidance. Explicit settings remain unchanged.
+
+Keep these settings for the first `vp pack` run. After validation, review whether your package can adopt the new defaults:
+
+- Removing `deps.resolveDepSubpath: true` [preserves external subpath imports as written](https://tsdown.dev/options/dependencies#deps-resolvedepsubpath). Check that consumers can resolve the emitted imports.
+- Removing the inserted `attw.profile: 'strict'` selects the `esm-only` [resolution profile](https://tsdown.dev/options/lint#profiles). This skips `node10` and CommonJS resolution checks. Keep `strict` if your package requires those checks.
+
+Remove each accepted setting's generated comment too. Run `vp pack` and your package's consumer checks after each change. Keep the setting when you cannot validate the result.
+
 If your project uses a `tsdown.config.ts`, move its options into the `pack` block in `vite.config.ts`:
 
 ```ts [tsdown.config.ts] {4-6}

package/docs/guide/monorepo.md

@@ -6,7 +6,13 @@ Because `vite.config.ts` is just JavaScript, you can choose to put your entire c
 
 ## Root Config With Overrides
 
-Vite+ does not currently support nested lint or format configuration. Package-level `lint` and `fmt` blocks are not automatically applied. For now, define file- or package-specific settings with overrides in the root `vite.config.ts`. The long-term behavior is open for discussion; [share your use case and expectations](/guide/troubleshooting#nested-lint-or-format-config-is-not-applied) to help shape it.
+Run `vp lint`, `vp fmt`, and `vp check` from the workspace root to apply the root lint and format settings across packages. These commands do not apply nested configs to individual files. Define file- or package-specific settings with overrides in the root `vite.config.ts`.
+
+When run from a package directory, `vp lint` and `vp fmt` still use the root settings unless the package config defines its own `lint` or `fmt` block. We do not recommend package-level blocks; use overrides in the root config instead. File arguments remain relative to the package working directory.
+
+`vp check` uses the root `lint` and `fmt` blocks when they exist. Package configs cannot replace root format settings, lint rules, or type-check options in `vp check`.
+
+Use `-c <path>` or `--config <path>` with `vp lint` or `vp fmt` to select another config explicitly.
 
 Use `lint.overrides` for Oxlint rules that only apply to some packages:
 

package/docs/guide/run.md

@@ -95,7 +95,9 @@ export default defineConfig({
       build: {
         command: 'vp build',
         dependsOn: ['lint'],
-        env: ['NODE_ENV'],
+        cache: {
+          env: ['NODE_ENV'],
+        },
       },
       deploy: {
         command: 'deploy-script --prod',

package/docs/guide/test.md

@@ -2,6 +2,8 @@
 
 `vp test` runs tests with [Vitest](https://vitest.dev).
 
+The bundled runner uses Vitest `5.0.1` and 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.
+
 ## Overview
 
 `vp test` is built on [Vitest](https://vitest.dev/), so you get a Vite-native test runner that reuses your Vite config and plugins, supports Jest-style expectations, snapshots, and coverage, and handles modern ESM, TypeScript, and JSX projects cleanly.

package/docs/guide/troubleshooting.md

@@ -26,13 +26,13 @@ The Oxlint type checker path powered by `tsgolint` does not support `baseUrl`. `
 
 ## Nested lint or format config is not applied
 
-Vite+ does not currently support nested lint or format configuration. When running `vp lint`, `vp fmt`, or `vp check` from the workspace root, do not rely on configs in subdirectories or on `lint` and `fmt` blocks in package-level `vite.config.ts` files to override the root settings.
+When running `vp lint`, `vp fmt`, or `vp check`, configs in subdirectories do not override settings for individual files. `vp lint` and `vp fmt` let Oxlint and Oxfmt discover configuration from the working directory, so a `lint` or `fmt` block in a package config takes effect when run from that package, which we do not recommend. `vp check` selects the workspace-root `lint` and `fmt` blocks when they exist. Use `-c <path>` or `--config <path>` with `vp lint` or `vp fmt` to select another config explicitly.
 
 Keep lint and format settings in the root `vite.config.ts`. Use [`lint.overrides`](/guide/monorepo#root-config-with-overrides) and [`fmt.overrides`](/guide/monorepo#format-overrides) for file- or package-specific settings. You can also [import configuration objects](/guide/monorepo#composing-configuration-files) into the root config to keep settings in separate files.
 
-For IDE integration, we have `disableNestedConfig` and `fmt.disableNestedConfig` config to disable nested lint and format configs and keep editor behavior aligned with the root Vite+ config. See [IDE Integration](/guide/ide-integration) for setup instructions for your editor.
+For IDE integration, `disableNestedConfig` and `fmt.disableNestedConfig` disable per-file nested lint and format configs. See [IDE Integration](/guide/ide-integration) for setup instructions for your editor.
 
-We're holding off on nested config support for now. Some of the factors we're considering are how implicit config discovery affects the predictability of linting and formatting, what context AI agents need to understand the settings that apply, and the potential performance cost of finding and loading multiple configs. At the same time, we recognize that keeping package-specific context close to the code may have benefits. The use cases we've heard so far haven't given us a strong enough reason to commit to those semantics. Waiting leaves room to add support later, and we'd like to hear why your project needs nested configs, especially where root-level overrides fall short.
+We're holding off on applying nested configs to individual files for now. Some of the factors we're considering are how implicit config discovery affects the predictability of linting and formatting, what context AI agents need to understand the settings that apply, and the potential performance cost of finding and loading multiple configs. At the same time, we recognize that keeping package-specific context close to the code may have benefits. The use cases we've heard so far haven't given us a strong enough reason to commit to those semantics. Waiting leaves room to add support later, and we'd like to hear why your project needs nested configs, especially where root-level overrides fall short.
 
 Do you need nested configs? [Share your use case and opinion on GitHub](https://github.com/voidzero-dev/vite-plus/discussions/2669), including your project structure, the reason why you want them and whether root-level overrides meet your needs.