vite-plus 0.3.3 → 1.0.0-rc.1

package/dist/{tsconfig-C3h9CVTA.js → tsconfig-piorpNV7.js}

@@ -1,6 +1,7 @@
-import { p as createBaseUrlTsconfigFixArgs, t as BASEURL_TSCONFIG_FIX_PACKAGE } from "./constants-C2dTOTe-.js";
-import { c as parse, o as applyEdits, s as modify } from "./json-cULBl7Pi.js";
-import { S as log, b as confirm, k as isCancel, t as cancelAndExit } from "./prompts-k14KgthC.js";
+import { p as createBaseUrlTsconfigFixArgs, t as BASEURL_TSCONFIG_FIX_PACKAGE } from "./constants-BAsBfS1J.js";
+import { c as modify, l as parse, o as applyEdits } from "./json-JP24qHUF.js";
+import { t as vitest_v5_entry_points_default } from "./vitest-v5-entry-points-DthU1e_O.js";
+import { S as log, b as confirm, k as isCancel, t as cancelAndExit } from "./prompts-BW7_fDGJ.js";
 import { n as runCommandSilently } from "./command-CguLh2KL.js";
 import path from "node:path";
 import { styleText } from "node:util";
@@ -100,7 +101,10 @@ function removeDeprecatedTsconfigFalseOption(filePath, optionName) {
 	fs.writeFileSync(filePath, newText);
 	return true;
 }
-const TSCONFIG_TYPE_REPLACEMENTS = { "tsdown/client": "vite-plus/pack/client" };
+const TSCONFIG_TYPE_REPLACEMENTS = {
+	"tsdown/client": "vite-plus/pack/client",
+	...Object.fromEntries(Object.entries(vitest_v5_entry_points_default).filter(([source]) => source.startsWith("vite-plus/")))
+};
 function hasTypesToRewriteInTsconfig(filePath) {
 	let text;
 	try {

package/dist/version.js

@@ -1,8 +1,9 @@
 import { t as renderCliDoc } from "./help-BmKpeOP9.js";
 import { i as log, o as printHeader, t as accent } from "./terminal-MKGAuy-p.js";
-import { _ as version } from "./constants-C2dTOTe-.js";
-import { i as hasVitePlusDependency, n as detectPackageMetadata } from "./package-CHH8jWan.js";
+import { y as version } from "./constants-BAsBfS1J.js";
+import { i as hasVitePlusDependency, n as detectPackageMetadata } from "./package-BrupPpWA.js";
 import path from "node:path";
+import { pathToFileURL } from "node:url";
 import fs from "node:fs";
 //#region src/version.ts
 /** Tool display names in the order shown by `vp --version`. */
@@ -45,7 +46,8 @@ function isVitePlusDeclaredInAncestors(cwd) {
 */
 async function resolveToolVersions(localPackagePath) {
 	try {
-		const mod = await import(`${localPackagePath}/dist/versions.js`);
+		const file = path.join(localPackagePath, "dist", "versions.js");
+		const mod = await import(pathToFileURL(file).href);
 		if (mod.versions && typeof mod.versions === "object") return mod.versions;
 	} catch {}
 	return {};

package/dist/versions.js

@@ -1,9 +1,9 @@
 export const versions = {
-  "vite": "8.3.0",
-  "rolldown": "1.2.9",
-  "vitest": "4.1.11",
-  "oxfmt": "0.68.0",
-  "oxlint": "1.83.0",
-  "oxlint-tsgolint": "7.0.2001",
+  "vite": "8.3.1",
+  "rolldown": "1.2.11",
+  "vitest": "5.0.1",
+  "oxfmt": "0.70.0",
+  "oxlint": "1.85.0",
+  "oxlint-tsgolint": "7.0.2003",
   "tsdown": "0.23.0"
 };

package/dist/vitest-ecosystem-BU0AqZq-.js

@@ -0,0 +1,23 @@
+//#region src/utils/vitest-ecosystem.ts
+/** Official packages that share the bundled runner's release version. */
+const VITEST_EXACT_VERSION_PACKAGES = /* @__PURE__ */ new Set([
+	"@vitest/browser",
+	"@vitest/browser-playwright",
+	"@vitest/browser-preview",
+	"@vitest/coverage-v8",
+	"@vitest/coverage-istanbul",
+	"@vitest/mocker",
+	"@vitest/pretty-format",
+	"@vitest/snapshot",
+	"@vitest/spy",
+	"@vitest/ui",
+	"@vitest/utils",
+	"@vitest/web-worker"
+]);
+/** Optional peers fall back to the project; unrelated @vitest packages do not redirect. */
+const VITEST_RESOLVER_PACKAGES = /* @__PURE__ */ new Set(["vitest", ...VITEST_EXACT_VERSION_PACKAGES]);
+function isAlignableVitestEcosystemPackage(name) {
+	return VITEST_EXACT_VERSION_PACKAGES.has(name);
+}
+//#endregion
+export { isAlignableVitestEcosystemPackage as n, VITEST_RESOLVER_PACKAGES as t };

package/dist/vitest-v5-entry-points-DthU1e_O.js

@@ -0,0 +1,25 @@
+//#region src/vitest-v5-entry-points.json
+var vitest_v5_entry_points_default = {
+	"vitest/coverage": "vite-plus/test/node",
+	"vitest/reporters": "vite-plus/test/node",
+	"vitest/environments": "vite-plus/test/runtime",
+	"vitest/snapshot": "vite-plus/test/runtime",
+	"vitest/mocker": "vite-plus/test/mocker",
+	"vite-plus/test/coverage": "vite-plus/test/node",
+	"vite-plus/test/reporters": "vite-plus/test/node",
+	"vite-plus/test/environments": "vite-plus/test/runtime",
+	"vite-plus/test/snapshot": "vite-plus/test/runtime",
+	"vitest/browser-webdriverio": "@vitest/browser-webdriverio",
+	"vitest/browser-webdriverio/context": "vite-plus/test/browser/context",
+	"vitest/browser/providers/webdriverio": "@vitest/browser-webdriverio",
+	"vitest/browser/providers/webdriverio/context": "vite-plus/test/browser/context",
+	"vitest/plugins/browser-webdriverio": "@vitest/browser-webdriverio",
+	"vite-plus/test/browser-webdriverio": "@vitest/browser-webdriverio",
+	"vite-plus/test/browser-webdriverio/context": "vite-plus/test/browser/context",
+	"vite-plus/test/browser/providers/webdriverio": "@vitest/browser-webdriverio",
+	"vite-plus/test/browser/providers/webdriverio/context": "vite-plus/test/browser/context",
+	"vite-plus/test/plugins/browser-webdriverio": "@vitest/browser-webdriverio",
+	"@vitest/browser/providers/webdriverio": "@vitest/browser-webdriverio"
+};
+//#endregion
+export { vitest_v5_entry_points_default as t };

package/docs/config/fmt.md

@@ -1,6 +1,8 @@
 # Format Config
 
-`vp fmt` and `vp check` read Oxfmt settings from the `fmt` block in the root `vite.config.ts`. See [Oxfmt's configuration](https://oxc.rs/docs/guide/usage/formatter/config.html) for details.
+`vp fmt` uses Oxfmt's [native config discovery](/guide/fmt#configuration) from the working directory. Use `vp fmt -c <path>` or `vp fmt --config <path>` to select another config. See [Oxfmt's configuration](https://oxc.rs/docs/guide/usage/formatter/config.html) for details.
+
+`vp check` uses the workspace-root `fmt` block when it exists, including from a package directory. Package configs do not replace these format settings in `vp check`.
 
 ## Example
 
@@ -19,4 +21,4 @@ export default defineConfig({
 
 For file- or package-specific formatting settings, use [`fmt.overrides`](/guide/monorepo#format-overrides) from the root `vite.config.ts`.
 
-Vite+ does not currently support nested format configuration. See [troubleshooting](/guide/troubleshooting#nested-lint-or-format-config-is-not-applied) for details and how to give feedback on future support.
+Oxfmt disables nested configs in Vite+ mode, so nested format configs do not override settings for individual files. See [troubleshooting](/guide/troubleshooting#nested-lint-or-format-config-is-not-applied) for details.

package/docs/config/lint.md

@@ -1,6 +1,8 @@
 # Lint Config
 
-`vp lint` and `vp check` read Oxlint settings from the `lint` block in the root `vite.config.ts`. See [Oxlint's configuration](https://oxc.rs/docs/guide/usage/linter/config.html) for details.
+`vp lint` uses Oxlint's [native config discovery](/guide/lint#configuration) from the working directory. Use `vp lint -c <path>` or `vp lint --config <path>` to select another config. See [Oxlint's configuration](https://oxc.rs/docs/guide/usage/linter/config.html) for details.
+
+`vp check` uses the workspace-root `lint` block when it exists, including from a package directory. Package configs do not replace these lint settings in `vp check`.
 
 ## Example
 
@@ -25,4 +27,4 @@ We recommend enabling both `options.typeAware` and `options.typeCheck` so `vp li
 
 For file- or package-specific lint rules, use [`lint.overrides`](/guide/monorepo#root-config-with-overrides) from the root `vite.config.ts`.
 
-Vite+ does not currently support nested lint configuration. See [troubleshooting](/guide/troubleshooting#nested-lint-or-format-config-is-not-applied) for details and how to give feedback on future support.
+Oxlint disables nested configs in Vite+ mode, so nested lint configs do not override settings for individual files. See [troubleshooting](/guide/troubleshooting#nested-lint-or-format-config-is-not-applied) for details.

package/docs/config/run.md

@@ -80,7 +80,7 @@ tasks: {
 }
 ```
 
-Use the object form when a task needs other fields like `cache`, `dependsOn`, `env`, or `input`.
+Use the object form when a task needs other fields like `cache`, `dependsOn`, or `cwd`.
 
 ### `command`
 
@@ -156,10 +156,26 @@ See [Task Dependencies](/guide/run#task-dependencies) for details on how explici
 
 ### `cache`
 
-- **Type:** `boolean`
+- **Type:** `boolean | { env?: string[], untrackedEnv?: string[], input?: Array<...>, output?: Array<...> }`
 - **Default:** `true`
 
-Whether to cache this task's output. Set to `false` for tasks that should never be cached, like dev servers:
+Whether and how to cache this task. Caching is enabled with default settings when `cache` is omitted, `true`, or `{}`.
+
+Use an object to configure how the task is cached with [`cache.env`](#cache-env), [`cache.untrackedEnv`](#cache-untrackedenv), [`cache.input`](#cache-input), and [`cache.output`](#cache-output):
+
+```ts [vite.config.ts]
+tasks: {
+  build: {
+    command: 'node build.mjs',
+    cache: {
+      env: ['NODE_ENV'],
+      input: [{ auto: true }, '!dist/**'],
+    },
+  },
+}
+```
+
+Set `cache` to `false` for tasks that should never be cached, like dev servers:
 
 ```ts [vite.config.ts]
 tasks: {
@@ -170,7 +186,7 @@ tasks: {
 }
 ```
 
-### `env`
+### `cache.env`
 
 - **Type:** `string[]`
 - **Default:** `[]`
@@ -181,7 +197,9 @@ Environment variables included in the cache fingerprint. When any listed variabl
 tasks: {
   build: {
     command: 'node build.mjs',
-    env: ['NODE_ENV'],
+    cache: {
+      env: ['NODE_ENV'],
+    },
   },
 }
 ```
@@ -195,7 +213,7 @@ $ NODE_ENV=development vp run build    # first run
 $ NODE_ENV=production vp run build     # cache miss: env 'NODE_ENV' changed
 ```
 
-### `untrackedEnv`
+### `cache.untrackedEnv`
 
 - **Type:** `string[]`
 - **Default:** see below
@@ -206,12 +224,14 @@ Environment variables passed to the task process but **not** included in the cac
 tasks: {
   build: {
     command: 'node build.mjs',
-    untrackedEnv: ['CI', 'GITHUB_ACTIONS'],
+    cache: {
+      untrackedEnv: ['CI', 'GITHUB_ACTIONS'],
+    },
   },
 }
 ```
 
-`untrackedEnv` accepts the same wildcard and `!` exclusion patterns as [`env`](#env).
+`untrackedEnv` accepts the same wildcard and `!` exclusion patterns as [`env`](#cache-env).
 
 Do not put a variable in `untrackedEnv` if its value changes the task result. If a cache-reporting tool covers the variable through [automatic tracking](/guide/automatic-data-tracking#cooperative-tracking), leave it out of both `env` and `untrackedEnv`.
 
@@ -219,10 +239,10 @@ Vite Task passes a set of common environment variables to all tasks:
 
 - **System:** `HOME`, `USER`, `PATH`, `SHELL`, `LANG`, `TZ`
 - **Node.js:** `NODE_OPTIONS`, `COREPACK_HOME`, `PNPM_HOME`
-- **CI/CD:** `CI`, `VERCEL_*`, `NEXT_*`
+- **CI/CD:** `CI`, `VERCEL_*`, `NEXT_*`, `GITHUB_*`, `RUNNER_*`, `ACTIONS_ID_TOKEN_REQUEST_URL`, `ACTIONS_ID_TOKEN_REQUEST_TOKEN`
 - **Terminal:** Color variables (`FORCE_COLOR`, `NO_COLOR`, `COLORTERM`, `TERM`, `TERM_PROGRAM`) aren't passed to tasks unless you list them under `env` (the value gets fingerprinted, so changing it invalidates the cache) or `untrackedEnv` (passed without fingerprinting). If `FORCE_COLOR` isn't in either list, the child gets `FORCE_COLOR=1` so cached logs stay colored. Colors get stripped on display when the terminal can't render them.
 
-### `input`
+### `cache.input`
 
 - **Type:** `Array<string | { auto: boolean } | { pattern: string, base: "workspace" | "package" }>`
 - **Default:** `[{ auto: true }]` (auto-inferred)
@@ -235,8 +255,10 @@ Vite Task automatically detects which files a command uses. See [Automatic Data
 tasks: {
   build: {
     command: 'vp build',
-    // Use `{ auto: true }` to use automatic fingerprinting (default).
-    input: [{ auto: true }, '!**/*.tsbuildinfo', '!dist/**'],
+    cache: {
+      // Use `{ auto: true }` to use automatic fingerprinting (default).
+      input: [{ auto: true }, '!**/*.tsbuildinfo', '!dist/**'],
+    },
   },
 }
 ```
@@ -247,7 +269,9 @@ tasks: {
 tasks: {
   build: {
     command: 'vp build',
-    input: ['src/**/*.ts', 'vite.config.ts'],
+    cache: {
+      input: ['src/**/*.ts', 'vite.config.ts'],
+    },
   },
 }
 ```
@@ -258,10 +282,12 @@ tasks: {
 tasks: {
   build: {
     command: 'vp build',
-    input: [
-      { auto: true },
-      { pattern: 'shared-config/**', base: 'workspace' },
-    ],
+    cache: {
+      input: [
+        { auto: true },
+        { pattern: 'shared-config/**', base: 'workspace' },
+      ],
+    },
   },
 }
 ```
@@ -277,7 +303,9 @@ The `base` field is required and controls how the glob pattern is resolved:
 tasks: {
   greet: {
     command: 'node greet.mjs',
-    input: [],
+    cache: {
+      input: [],
+    },
   },
 }
 ```
@@ -286,7 +314,7 @@ tasks: {
 String glob patterns are resolved relative to the package directory by default. Use the object form with `base: "workspace"` to resolve relative to the workspace root.
 :::
 
-### `output`
+### `cache.output`
 
 - **Type:** `Array<string | { auto: boolean } | { pattern: string, base: "workspace" | "package" }>`
 - **Default:** automatic write tracking
@@ -299,7 +327,9 @@ If you omit `output`, Vite Task uses automatic write tracking to choose those fi
 tasks: {
   build: {
     command: 'node build.mjs',
-    output: ['dist/**', '!dist/cache/**'],
+    cache: {
+      output: ['dist/**', '!dist/cache/**'],
+    },
   },
 }
 ```
@@ -312,7 +342,9 @@ This is useful when a task writes files that should not be restored from the cac
 tasks: {
   typecheck: {
     command: 'tsc --build',
-    output: [{ auto: true }, '!*.tsbuildinfo'],
+    cache: {
+      output: [{ auto: true }, '!*.tsbuildinfo'],
+    },
   },
 }
 ```
@@ -323,10 +355,12 @@ If a task writes outside its own package, use the object form with `base: "works
 tasks: {
   build: {
     command: 'node build.mjs',
-    output: [
-      'dist/**',
-      { pattern: 'shared-artifacts/**', base: 'workspace' },
-    ],
+    cache: {
+      output: [
+        'dist/**',
+        { pattern: 'shared-artifacts/**', base: 'workspace' },
+      ],
+    },
   },
 }
 ```
@@ -337,7 +371,9 @@ Set `output: []` to disable output restoration for a cached task:
 tasks: {
   report: {
     command: 'node scripts/report.mjs',
-    output: [],
+    cache: {
+      output: [],
+    },
   },
 }
 ```

package/docs/guide/automatic-data-tracking.md

@@ -4,7 +4,7 @@ Automatic data tracking is how Vite Task learns what inputs a task needs for cac
 
 When you run a cache-enabled task, Vite Task observes the task's execution and records what files were read and written, as well as any metadata reported by the task. On the next run, Vite Task uses the recorded fingerprint to decide whether to replay the cache or run the task.
 
-Use this page when you need to understand why a task hits or misses the cache, or when you need to decide whether to add `input`, `output`, `env`, or `untrackedEnv` config.
+Use this page when you need to understand why a task hits or misses the cache, or when you need to decide whether to add `cache.input`, `cache.output`, `cache.env`, or `cache.untrackedEnv` config.
 
 ## Tracking Tiers
 
@@ -19,7 +19,7 @@ Vite Task starts with file system tracking for any command. A cache-reporting to
 
 ## File System Tracking
 
-File system tracking applies to every cache-enabled task. If you omit [`input`](/config/run#input), Vite Task tracks the files a command reads while it runs:
+File system tracking applies to every cache-enabled task. If you omit [`cache.input`](/config/run#cache-input), Vite Task tracks the files a command reads while it runs:
 
 ```ts [vite.config.ts]
 import { defineConfig } from 'vite-plus';
@@ -37,7 +37,7 @@ export default defineConfig({
 
 For this task, Vite Task records source files, config files, missing files the command checked, and directories the command scanned. Subsequent runs re-run the task when one of those tracked inputs changes.
 
-File system tracking also tracks outputs. If you omit [`output`](/config/run#output), Vite Task archives files the command writes after a successful run and restores them on a cache hit.
+File system tracking also tracks outputs. If you omit [`cache.output`](/config/run#cache-output), Vite Task archives files the command writes after a successful run and restores them on a cache hit.
 
 ### Limitations
 
@@ -45,13 +45,13 @@ Vite Task cannot track environment variable reads, and it cannot always tell whi
 
 Use [Override Inputs And Outputs](#override-inputs-and-outputs) when file system tracking includes files that should not affect the cache, misses files that should, or restores the wrong outputs.
 
-Use [`env`](/config/run#env) when a command needs an environment variable and the value should affect the cache, or [`untrackedEnv`](/config/run#untrackedenv) when the value should not affect the cache.
+Use [`cache.env`](/config/run#cache-env) when a command needs an environment variable and the value should affect the cache, or [`cache.untrackedEnv`](/config/run#cache-untrackedenv) when the value should not affect the cache.
 
 These limitations do not apply to `vp build`: Vite reports [Cooperative Tracking](#cooperative-tracking) metadata automatically, including `VITE_*`, `NODE_ENV`, and Vite-managed cache paths that should not become inputs or outputs. A standard `vp build` task does not need manual `input`, `output`, or `env`.
 
 ### Override Inputs And Outputs
 
-[`input`](/config/run#input) controls what invalidates the cache. [`output`](/config/run#output) controls which files Vite Task restores on a cache hit.
+[`cache.input`](/config/run#cache-input) controls what invalidates the cache. [`cache.output`](/config/run#cache-output) controls which files Vite Task restores on a cache hit.
 
 Both options use the same syntax and can be configured separately.
 
@@ -65,12 +65,13 @@ Both options use the same syntax and can be configured separately.
 tasks: {
   build: {
     command: 'node build.mjs',
+    cache: {
+      // Keep automatic input tracking, but exclude `dist` from inputs.
+      input: [{ auto: true }, '!dist/**'],
 
-    // Keep automatic input tracking, but exclude `dist` from inputs.
-    input: [{ auto: true }, '!dist/**'],
-
-    // Disable automatic output tracking and restore only `dist/**` on a cache hit.
-    output: ['dist/**'],
+      // Disable automatic output tracking and restore only `dist/**` on a cache hit.
+      output: ['dist/**'],
+    },
   },
 }
 ```
@@ -81,8 +82,10 @@ Use explicit `input` globs only when you know the command's full input set. This
 tasks: {
   lint: {
     command: 'vp lint',
-    // Disable automatic input tracking and fingerprint only these files.
-    input: ['src/**', 'vite.config.ts'],
+    cache: {
+      // Disable automatic input tracking and fingerprint only these files.
+      input: ['src/**', 'vite.config.ts'],
+    },
   },
 }
 ```
@@ -93,7 +96,9 @@ Set `input: []` when no files should affect the cache fingerprint. This is rarel
 tasks: {
   downloadSchema: {
     command: 'curl -O https://example.com/schema.json',
-    input: [],
+    cache: {
+      input: [],
+    },
   },
 }
 ```
@@ -128,13 +133,13 @@ export default defineConfig({
 
 Run this task with `vpr frontendBuild` or `vp run frontendBuild`.
 
-Manual config overrides reported metadata. Add `input`, `output`, `env`, or `untrackedEnv` when your project has behavior that Vite cannot report.
+Manual config overrides reported metadata. Add `cache.input`, `cache.output`, `cache.env`, or `cache.untrackedEnv` when your project has behavior that Vite cannot report.
 
 Vite+ supports cooperative tracking for `vp build` today. It will extend this support to more first-party tools in the future. Third-party tools can report cache metadata with [`@voidzero-dev/vite-task-client`](https://npmx.dev/package/@voidzero-dev/vite-task-client).
 
 ## When To Add Manual Config
 
-Add config when your project has behavior the command or tool cannot know.
+Add config when your project has behavior the command or tool cannot know. These options go under the task's [`cache`](/config/run#cache) object.
 
 | Case                                                              | Example                                                                                         |
 | ----------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |

package/docs/guide/cache.md

@@ -7,7 +7,7 @@ Vite Task can automatically track dependencies and cache tasks run through `vp r
 When a task runs successfully (exit code 0), its terminal output (stdout/stderr) and all written files (output files) are saved. On the next run, Vite Task checks if anything changed:
 
 1. **Arguments:** did the [additional arguments](/guide/run#additional-arguments) passed to the task change?
-2. **Environment variables:** did any [fingerprinted env vars](/config/run#env) change?
+2. **Environment variables:** did any [fingerprinted env vars](/config/run#cache-env) change?
 3. **Inputs:** did any input file that the command reads change?
 
 When all checks match, Vite Task replays the cached terminal output, restores saved output files, and skips the command.
@@ -50,14 +50,16 @@ Vite Task uses [automatic data tracking](/guide/automatic-data-tracking) to lear
 - **File system tracking:** Vite Task records file reads, missing-file probes, directory listings, and written output files for every task with cache enabled.
 - **Cooperative tracking:** cache-reporting tools can report metadata that file system tracking cannot infer. Vite+ supports this for `vp build` today.
 
-Use [`input`](/config/run#input) or [`output`](/config/run#output) when a task needs manual tracking rules. `input` controls what invalidates the cache. `output` controls which files Vite Task restores on a cache hit.
+Use [`cache.input`](/config/run#cache-input) or [`cache.output`](/config/run#cache-output) when a task needs manual tracking rules. `input` controls what invalidates the cache. `output` controls which files Vite Task restores on a cache hit.
 
 ```ts [vite.config.ts]
 tasks: {
   build: {
     command: 'node build.mjs',
-    input: [{ auto: true }, '!dist/**'],
-    output: ['dist/**'],
+    cache: {
+      input: [{ auto: true }, '!dist/**'],
+      output: ['dist/**'],
+    },
   },
 }
 ```
@@ -66,20 +68,22 @@ tasks: {
 
 By default, tasks run in a clean environment. Only a small set of common variables, such as `PATH`, `HOME`, and `CI`, are passed through. Other environment variables are neither visible to the task nor included in the cache fingerprint.
 
-To add an environment variable to the cache key, add it to [`env`](/config/run#env). Changing its value then invalidates the cache:
+To add an environment variable to the cache key, add it to [`cache.env`](/config/run#cache-env). Changing its value then invalidates the cache:
 
 ```ts [vite.config.ts]
 tasks: {
   build: {
     command: 'webpack --mode production',
-    env: ['NODE_ENV'],
+    cache: {
+      env: ['NODE_ENV'],
+    },
   },
 }
 ```
 
-To pass a variable to the task **without** affecting cache behavior, use [`untrackedEnv`](/config/run#untrackedenv). This is useful for variables like `CI` or `GITHUB_ACTIONS` that should be available in the task, but do not affect caching behavior.
+To pass a variable to the task **without** affecting cache behavior, use [`cache.untrackedEnv`](/config/run#cache-untrackedenv). This is useful for variables like `CI` or `GITHUB_ACTIONS` that should be available in the task, but do not affect caching behavior.
 
-See [Run Config](/config/run#env) for details on wildcard patterns and the full list of automatically passed-through variables.
+See [Run Config](/config/run#cache-env) for details on wildcard patterns and the full list of automatically passed-through variables.
 
 ## Cache Sharing
 

package/docs/guide/check.md

@@ -29,6 +29,8 @@ vp check --no-fmt --no-lint # Type-check only (requires `typeCheck` enabled).
 - [`fmt`](/guide/fmt#configuration) block in `vite.config.ts`
 - TypeScript project structure and tsconfig files for type-aware linting
 
+When run from a workspace package, `vp check` uses the workspace-root `lint` and `fmt` blocks. Package configs cannot replace root format settings, lint rules, or type-check options. File paths and TypeScript projects are still resolved from the package working directory.
+
 Recommended base `lint` config:
 
 ```ts [vite.config.ts]

package/docs/guide/commit-hooks.md

@@ -80,7 +80,14 @@ Project-owned hook scripts such as `.vite-hooks/pre-commit` should be committed
 
 ### `vp staged`
 
-`vp staged` runs staged-file checks using the `staged` config from `vite.config.ts`. To run it before each commit, add it to the project-owned pre-commit hook:
+`vp staged` runs staged-file checks using the `staged` config from `vite.config.ts`. It bundles `lint-staged` 17 and requires:
+
+- Node.js `22.22.1` or later in the `22.x` line, or `24.11.0` or later
+- Git `2.32.0` or later
+
+Node.js `20.x` is no longer supported for staged checks. These requirements also apply when a pre-commit hook runs `vp staged`. Upgrade the project's Node.js runtime and the Git installation on developer machines and CI runners before using the command. See the [lint-staged 17 release notes](https://github.com/lint-staged/lint-staged/releases/tag/v17.0.0) for the upstream changes.
+
+To run it before each commit, add it to the project-owned pre-commit hook:
 
 ```bash
 vp staged

package/docs/guide/env.md

@@ -65,16 +65,16 @@ Package-manager selection uses this priority:
 4. `devEngines.packageManager`
 5. Lockfile or manager-specific configuration
 6. The named package manager's global default version
-7. The named shim's latest release
+7. The named shim's latest release (Node.js' bundled version for `npm`)
 
 `VP_PACKAGE_MANAGER` selects the manager and version for commands such as `vp install`. Direct package-manager shims ignore this variable and use independent version overrides:
 
-| Variable          | Shims             |
-| ----------------- | ----------------- |
-| `VP_NPM_VERSION`  | `npm`, `npx`      |
-| `VP_PNPM_VERSION` | `pnpm`, `pnpx`    |
-| `VP_YARN_VERSION` | `yarn`, `yarnpkg` |
-| `VP_BUN_VERSION`  | `bun`, `bunx`     |
+| Variable          | Shims                       |
+| ----------------- | --------------------------- |
+| `VP_NPM_VERSION`  | `npm`, `npx`                |
+| `VP_PNPM_VERSION` | `pnpm`, `pnpx`, `pn`, `pnx` |
+| `VP_YARN_VERSION` | `yarn`, `yarnpkg`           |
+| `VP_BUN_VERSION`  | `bun`, `bunx`               |
 
 These variables accept a version or range, such as `10.18.0`, `10`, or `latest`, and override the matching shim's project and default versions. They do not change the manager or version selected by `vp install`.
 
@@ -89,12 +89,14 @@ VP_PNPM_VERSION=10.20.0 pnpm --version
 
 The overrides apply in managed mode. A package manager can also perform its own version switching after Vite+ launches it; for example, pnpm's `managePackageManagerVersions` setting may switch back to the version in `package.json`.
 
-A project selection applies only to its matching shims. For example, pnpm controls `pnpm` and `pnpx`; invoking `npm` still resolves npm independently. Without a matching project selection, a named shim uses its configured default version and otherwise uses the latest release without prompting. The directly invoked npm shim keeps its Node-bundled fallback, while an explicit `vp env ... npm` family scope uses standalone npm's latest release.
+A project selection applies only to its matching shims. For example, pnpm controls `pnpm`, `pnpx`, `pn`, and `pnx`; invoking `npm` still resolves npm independently. Without a matching project selection, a named shim uses its configured default version and otherwise uses the latest release without prompting. The npm shim falls back to Node's bundled npm. `vp env use npm` selects standalone npm's latest release for the current shell when no project version or global default is configured.
 
 ::: details Latest-version caching
 When a named shim falls back to the latest release, the resolved version is cached for one hour. An expired cache remains available when the registry cannot be reached.
 :::
 
+`pn` runs the same managed binary as `pnpm`, and `pnx` runs the same managed binary as `pnpx` (`pnpm dlx`). These aliases also work with managed pnpm versions older than v11.
+
 ## Environment Modes
 
 Managed mode is on by default, so Node.js and configured package-manager shims resolve through Vite+ and pick the right versions for the current project. Fresh installers record managed mode for npm, pnpm, Yarn, and Bun after the user enables environment management.
@@ -120,17 +122,20 @@ If you do not want Vite+ to manage Node.js first, run:
 vp env off
 ```
 
-This switches both components to system-first mode. Vite+ prefers system tools and falls back to managed installations. Mixed configurations compose: a system package-manager launcher receives the Node.js selected by the Node mode.
+This switches both components to system-first mode. Vite+ prefers system tools and falls back to managed installations. Mixed configurations compose: package-manager launchers that look up Node.js through PATH receive the runtime selected by the Node mode.
 
-Using `pm` records the selected mode for all currently supported package managers and replaces their individual choices. An unscoped `on` or `off` does the same while also changing Node.js. A family without a recorded mode remains undecided until its shim is first used or an `on` / `off` command configures it.
+Using `pm` records the selected mode for all currently supported package managers and replaces their individual choices. An unscoped `on` or `off` does the same while also changing Node.js.
 
 ## Commands
 
 ### Setup
 
-- `vp env setup` creates or updates the `node`, `npm`, `npx`, `pnpm`, `pnpx`, `yarn`, `yarnpkg`, `bun`, `bunx`, `vpx`, and `vpr` shims in the resolved bin directory. It writes shell setup scripts in the config directory.
-- `vp env on` / `vp env off` changes both modes; append `node`, `pm`, `npm`, `pnpm`, `yarn`, or `bun` to narrow the change
-- `vp env print` prints PATH setup for both components; append a selector to print one
+- `vp env setup` creates tool shims and writes shell setup scripts.
+- `vp env setup --refresh` recreates Vite+ shims and regenerates shell setup scripts using your saved preferences.
+- `vp env on` / `vp env off` switches between Vite+-managed and system-first modes; append `node`, `pm`, `npm`, `pnpm`, `yarn`, or `bun` to narrow the change.
+- `vp env print` prints PATH setup for both components; append a selector to print one.
+
+Upgrades refresh the setup automatically. Open a new terminal or reload your shell setup script afterward.
 
 PowerShell needs to dot-source the generated setup script in the current shell before `vp env use` can affect only that shell session:
 

package/docs/guide/fmt.md

@@ -20,9 +20,13 @@ vp fmt . --write
 
 Put formatting configuration directly in the `fmt` block in the root `vite.config.ts` so all your configuration stays in one place. We do not recommend using `.oxfmtrc.json` with Vite+.
 
-Vite+ does not currently support nested format configuration. For now, use [`fmt.overrides`](/guide/monorepo#format-overrides) in the root `vite.config.ts` for file- or package-specific options. 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 fmt` finds its config from the working directory, so package directories without their own `fmt` block use the root config. Relative file arguments retain their meaning. Use [`fmt.overrides`](/guide/monorepo#format-overrides) for file- or package-specific options instead of adding `fmt` blocks to package configs.
 
-For editors, disable nested formatter configs so format-on-save uses the root Vite+ `fmt` block:
+`vp check` uses the workspace-root `fmt` block when it exists, including from a package directory. Package configs cannot replace those format settings in `vp check`.
+
+An explicit `vp fmt -c <path>` or `vp fmt --config <path>` selects another config. Otherwise, Oxfmt discovers the nearest `vite.config.*` file with a `fmt` block. Supported extensions are `.js`, `.mjs`, `.ts`, `.cjs`, `.mts`, and `.cts`. Nested configs do not override settings for individual files.
+
+For editors, disable nested formatter configs to prevent per-file overrides:
 
 ```json [.vscode/settings.json]
 {

package/docs/guide/index.md

@@ -8,7 +8,7 @@ Vite+ also ships a [global `vp` CLI](/guide/global-cli) that manages Node.js and
 
 If you already have a Vite project, run [`vp migrate`](/guide/migrate) to migrate it to Vite+, or give your coding agent our [migration prompt](/guide/migrate#migration-prompt).
 
-Building with an AI assistant? View and copy a ready-made setup prompt:
+Building with an AI assistant? View and copy a prompt to create a new project, migrate an existing project, or upgrade Vite+:
 
 <CopyPrompt />