vite-plus 0.2.6 → 0.2.8

package/dist/version.js

@@ -1,7 +1,6 @@
-import { m as version } from "./constants-CaXMuYUG.js";
-import { a as printHeader, r as log, t as accent } from "./terminal-uTv0ZaMr.js";
-import { i as hasVitePlusDependency, n as detectPackageMetadata } from "./package-CP5EUXlu.js";
-import { t as renderCliDoc } from "./help-YP84FSEz.js";
+import { a as printHeader, c as renderCliDoc, r as log, t as accent } from "./terminal-CrqqK8WT.js";
+import { m as version } from "./constants-BppDcRc1.js";
+import { i as hasVitePlusDependency, n as detectPackageMetadata } from "./package-hV-77cBb.js";
 import path from "node:path";
 import fs from "node:fs";
 //#region src/version.ts
@@ -30,7 +29,8 @@ function isVitePlusDeclaredInAncestors(cwd) {
 	while (true) {
 		const packageJsonPath = path.join(currentDir, "package.json");
 		try {
-			if (hasVitePlusDependency(JSON.parse(fs.readFileSync(packageJsonPath, "utf8")))) return true;
+			const pkg = JSON.parse(fs.readFileSync(packageJsonPath, "utf8"));
+			if (hasVitePlusDependency(pkg)) return true;
 		} catch {}
 		const parentDir = path.dirname(currentDir);
 		if (parentDir === currentDir) break;

package/dist/versions.js

@@ -1,9 +1,9 @@
 export const versions = {
-  "vite": "8.1.5",
-  "rolldown": "1.2.0",
-  "tsdown": "0.22.13",
-  "oxlint": "1.75.0",
-  "oxfmt": "0.60.0",
+  "vite": "8.2.0",
+  "rolldown": "1.2.2",
+  "tsdown": "0.22.14",
+  "oxlint": "1.76.0",
+  "oxfmt": "0.61.0",
   "oxlint-tsgolint": "7.0.2001",
   "vitest": "4.1.10"
 };

package/docs/config/index.md

@@ -33,3 +33,16 @@ Vite+ extends the basic Vite configuration with these additions:
 - [`test`](/config/test) for Vitest
 - [`pack`](/config/pack) for tsdown
 - [`staged`](/config/staged) for staged-file checks
+- [`defaultPackage`](#defaultpackage) for the default target of bare app commands at a workspace root
+
+## defaultPackage
+
+Default target directory for `vp dev` / `vp build` / `vp preview` / `vp pack` when you invoke them bare in the directory containing the config, an implicit [`vp -C <dir>`](/guide/monorepo#app-commands):
+
+```ts [vite.config.ts]
+export default {
+  defaultPackage: './frontend',
+};
+```
+
+vp reads the values without executing the config, so `defaultPackage` also works at repository roots with no vite-plus dependency (for example a Laravel or Rails repo whose Vite app lives in `frontend/`, with vite-plus installed only there). That static read is why the values must stay plain string literals rather than expressions. An explicit `-C` or positional target always wins over the config.

package/docs/config/staged.md

@@ -1,6 +1,7 @@
 # Staged Config
 
-`vp staged` and `vp config` read staged-file rules from the `staged` block in `vite.config.ts`. See the [Commit hooks guide](/guide/commit-hooks).
+`vp staged` reads staged-file rules from the `staged` block in `vite.config.ts`. See the
+[Commit hooks guide](/guide/commit-hooks).
 
 ## Example
 

package/docs/guide/build.md

@@ -7,7 +7,7 @@
 `vp build` runs the standard Vite production build through Vite+. Since it is directly based on Vite, the build pipeline and configuration model are the same as Vite. For more information about how Vite production builds work, see the [Vite guide](https://vite.dev/guide/build). Note that Vite+ uses Vite 8 and [Rolldown](https://rolldown.rs/) for builds.
 
 ::: info
-`vp build` always runs the built-in Vite production build. If your project also has a `build` script in `package.json`, run `vp run build` when you want to run that script instead.
+`vp build` always runs the built-in Vite production build. If your project also has a `build` script in `package.json`, run `vp run build` when you want to run that script instead. See [Built-in Commands vs Scripts](/guide/run#built-in-commands-vs-scripts).
 :::
 
 ## Usage

package/docs/guide/ci.md

@@ -4,12 +4,12 @@ You can use `voidzero-dev/setup-vp` to use Vite+ in CI environments.
 
 ## Overview
 
-For GitHub Actions, the recommended setup is [`voidzero-dev/setup-vp`](https://github.com/voidzero-dev/setup-vp). It installs Vite+, sets up the required Node.js version and package manager, and can cache package installs automatically.
-
-That means you usually do not need separate `setup-node`, package-manager setup, and manual dependency-cache steps in your workflow.
+[`voidzero-dev/setup-vp`](https://github.com/voidzero-dev/setup-vp) provides integrations for GitHub Actions and GitLab CI/CD. Both install Vite+ and can install project dependencies. The GitHub Action can also set up Node.js and cache package manager data automatically, while the GitLab CI/CD template uses the Node.js runtime and cache configuration provided by the job.
 
 ## GitHub Actions
 
+The GitHub Action sets up Vite+, the required Node.js version, and the package manager. This means you usually do not need separate `setup-node`, package-manager setup, or manual dependency caching steps in your workflow.
+
 ```yaml [.github/workflows/ci.yml]
 - uses: voidzero-dev/setup-vp@v1
   with:
@@ -27,6 +27,31 @@ With `cache: true`, `setup-vp` handles dependency caching for you automatically.
 `setup-vp` caches package-manager data. To reuse Vite Task results across CI runs, add a separate [GitHub Actions cache for Vite Task](/guide/github-actions-cache).
 :::
 
+## GitLab CI/CD
+
+Use the reusable `setup-vp` remote template in your GitLab CI/CD configuration:
+
+```yaml [.gitlab-ci.yml]
+include:
+  - remote: 'https://raw.githubusercontent.com/voidzero-dev/setup-vp/v1/gitlab/setup-vp.yml'
+
+test:
+  extends: .setup-vp
+  image: node:24
+  script:
+    - vp check
+    - vp test
+    - vp build
+```
+
+The GitLab CI/CD integration differs from the GitHub Action in a few ways:
+
+- The template does not install Node.js. Use a Node.js image, as shown above, or otherwise provide Node.js in the job.
+- Configure dependency caching with the job's GitLab [`cache`](https://docs.gitlab.com/ci/yaml/#cache) keyword.
+- Use a Unix-like runner environment with Bash and either `curl` or `wget`.
+
+For advanced configuration and the complete input reference, see the [`setup-vp` GitLab CI/CD documentation](https://github.com/voidzero-dev/setup-vp#gitlab-cicd).
+
 ## Simplifying Existing Workflows
 
 If you are migrating an existing GitHub Actions workflow, you can often replace large blocks of Node, package-manager, and cache setup with a single `setup-vp` step.

package/docs/guide/commit-hooks.md

@@ -1,6 +1,7 @@
 # Commit Hooks
 
-Use `vp config` to install commit hooks, and `vp staged` to run checks on staged files.
+Use `vp config` to install the Git hook dispatcher, and `vp staged` to run checks on staged
+files.
 
 ## Overview
 
@@ -8,7 +9,7 @@ Vite+ supports commit hooks and staged-file checks without additional tooling.
 
 Use:
 
-- `vp config` to set up project hooks and related integrations
+- `vp config` to install generated hook infrastructure and related integrations
 - `vp staged` to run checks against the files currently staged in Git
 
 If you use [`vp create`](/guide/create) or [`vp migrate`](/guide/migrate), Vite+ prompts you to set this up for your project automatically.
@@ -17,7 +18,9 @@ If you use [`vp create`](/guide/create) or [`vp migrate`](/guide/migrate), Vite+
 
 ### `vp config`
 
-`vp config` configures Vite+ for the current project. It installs Git hooks, sets up the hook directory, and can also handle related project integration such as agent setup. By default, hooks are written to `.vite-hooks`:
+`vp config` configures Vite+ for the current project. It installs the generated Git hook
+dispatcher and can also handle related project integration such as agent setup. By default,
+project hooks are read from `.vite-hooks`:
 
 ```bash
 vp config
@@ -26,16 +29,21 @@ vp config --no-hooks
 vp config --no-agent
 ```
 
-Use `--no-hooks` when you want `vp config` to leave existing Git hook setup unchanged. Use
-`--no-agent` when you want it to skip updates to existing coding agent instruction files. You
-can pass both flags when you want `vp config` to skip both setup steps.
+Use `--no-hooks` when you want `vp config` to leave the Git hook dispatcher unchanged. Use
+`--no-agent` when you want it to skip updates to existing coding agent instruction files. You can
+pass both flags when you want `vp config` to skip both setup steps.
 
-You can also set `VITE_GIT_HOOKS=0` to disable hook installation from lifecycle scripts such as
+You can also set `VP_GIT_HOOKS=0` to disable hook installation from lifecycle scripts such as
 `prepare` or `postinstall`.
 
+Project-owned hook scripts such as `.vite-hooks/pre-commit` should be committed to the repository.
+The generated dispatcher and shims under `.vite-hooks/_` are ignored and recreated by `vp config`.
+`vp config` does not create or modify project hook scripts or staged-file configuration.
+
 ### `vp staged`
 
-`vp staged` runs staged-file checks using the `staged` config from `vite.config.ts`. If you set up Vite+ to handle your commit hooks, it will automatically run when you commit your local changes.
+`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:
 
 ```bash
 vp staged
@@ -43,6 +51,10 @@ vp staged --verbose
 vp staged --fail-on-changes
 ```
 
+```sh [.vite-hooks/pre-commit]
+vp staged
+```
+
 ## Configuration
 
 Define staged-file checks in the `staged` block in `vite.config.ts`:
@@ -57,4 +69,59 @@ export default defineConfig({
 });
 ```
 
-This is the default Vite+ approach and should replace separate `lint-staged` configuration in most projects. Because `vp staged` reads from `vite.config.ts`, your staged-file checks stay in the same place as your lint, format, test, build, and task-runner config.
+This is the default Vite+ approach and should replace separate `lint-staged` configuration in most
+projects. When you opt into hooks during `vp create`, Vite+ scaffolds both this configuration and
+the corresponding pre-commit hook. During `vp migrate`, existing hook policy is preserved, and
+the default is introduced only when no existing hook policy is found. Because
+`vp staged` reads from `vite.config.ts`, your staged-file checks stay in the same place as your
+lint, format, test, build, and task-runner config.
+
+## Disabling Hooks in Specific Environments
+
+The installed hooks check the environment on every run, so you can disable them per machine or per process without uninstalling anything. This is useful when commits happen outside development, for example through a flat file CMS or other processes.
+
+### Environment variable
+
+Set `VP_GIT_HOOKS=0` in the environment of the process that runs `git commit`, and every Vite+ hook exits immediately without running:
+
+```bash
+VP_GIT_HOOKS=0 git commit -m "content update"
+```
+
+`HUSKY=0` is honored the same way for ecosystem tooling compatibility. Setting `VP_GIT_HOOKS=0` in an environment also keeps `vp config` from reinstalling hooks there when a lifecycle script such as `prepare` runs.
+
+### Init script
+
+Before checking the environment variable, each hook sources an init script if one exists:
+
+1. `$XDG_CONFIG_HOME/vite-plus/hooks-init.sh` (defaults to `~/.config/vite-plus/hooks-init.sh`)
+2. `$XDG_CONFIG_HOME/husky/init.sh` as a fallback
+
+To disable hooks for a whole machine, create the init script and export the variable there:
+
+```sh [~/.config/vite-plus/hooks-init.sh]
+export VP_GIT_HOOKS=0
+```
+
+Because the hook itself reads this file, it works even when the committing process does not inherit your shell environment, for example if a daemon or web server is making commits.
+
+## Removing commit hooks
+
+To stop using the Vite+ hook dispatcher:
+
+1. Remove `vp config` from the `prepare` or `postinstall` script in `package.json`.
+
+2. Unset the Git hooks path that points at the Vite+ dispatcher:
+
+```bash
+git config --unset core.hooksPath
+```
+
+3. Remove the generated dispatcher directory (use your `--hooks-dir` value if you changed it):
+
+```bash
+rm -rf .vite-hooks/_
+```
+
+Project-owned scripts such as `.vite-hooks/pre-commit` and the `staged` block in `vite.config.ts`
+can remain for later use, or you can remove them separately if the project no longer needs them.

package/docs/guide/dev.md

@@ -6,6 +6,10 @@
 
 `vp dev` runs the standard Vite development server through Vite+, so you keep the normal Vite dev experience while using the same CLI entry point as the rest of the toolchain. For more information about using and configuring the dev server, see the [Vite guide](https://vite.dev/guide/).
 
+::: info
+`vp dev` always runs the built-in Vite dev server. If your project also has a `dev` script in `package.json`, run `vp run dev` when you want to run that script instead. See [Built-in Commands vs Scripts](/guide/run#built-in-commands-vs-scripts).
+:::
+
 ## Usage
 
 ```bash

package/docs/guide/env.md

@@ -6,12 +6,16 @@
 
 Managed mode is on by default, so `node`, `npm`, and related shims resolve through Vite+ and pick the right Node.js version for the current project.
 
-The project Node.js version is resolved from these sources, in priority order:
+Vite+ checks the current directory first, then walks up through its parents. The nearest directory
+with a supported declaration wins. Within each directory, sources are checked in this order:
 
-1. `.node-version` file (current or parent directories)
+1. `.node-version` file
 2. `devEngines.runtime` in `package.json` (the [devEngines standard](https://docs.npmjs.com/cli/v11/configuring-npm/package-json#devengines))
 3. `engines.node` in `package.json`
-4. The global default (`vp env default`), then the latest LTS
+4. `.nvmrc` file
+
+If no directory declares a version, Vite+ uses the global default (`vp env default`) and then the
+latest LTS.
 
 `devEngines.runtime` ranks above `engines.node` because it declares the development-environment requirement, while `engines.node` is a consumer-facing support range. `vp env doctor` warns when declared sources conflict.
 
@@ -112,7 +116,7 @@ vp env print                  # Print shell snippet for this session
 
 # Manage
 vp env pin lts                # Pin the project to the latest LTS release
-vp env install                # Install the version from .node-version or package.json
+vp env install                # Install the version from .node-version, package.json, or .nvmrc
 vp env default lts            # Set the global default version
 vp env use 20                 # Use Node.js 20 for the current shell session
 vp env use --unset            # Remove the session override

package/docs/guide/index.md

@@ -92,7 +92,7 @@ Vite+ can handle the entire local frontend development cycle from starting a pro
 
 - [`vp create`](/guide/create) creates new apps, packages, and monorepos.
 - [`vp migrate`](/guide/migrate) moves existing projects onto Vite+.
-- [`vp config`](/guide/commit-hooks) configures commit hooks and agent integration.
+- [`vp config`](/guide/commit-hooks) installs the Git hook dispatcher and configures agent integration.
 - [`vp staged`](/guide/commit-hooks) runs checks on staged files.
 - [`vp install`](/guide/install) installs dependencies with the right package manager.
 - [`vp env`](/guide/env) manages Node.js versions.

package/docs/guide/install.md

@@ -69,6 +69,8 @@ Use the `-g` flag for installing, updating or removing globally installed packag
 - `vp list -g [pkg]` lists global packages
 - `vp outdated -g [pkg]` prints outdated packages
 
+Updates keep the version spec a package was installed with: a package installed from a dist-tag (e.g. `vp install -g some-pkg@nightly`) updates to the newest version of that tag, and a version range stays within the range. Reinstall with a different spec (e.g. `vp update -g some-pkg@latest`) to switch, or pass `--latest` to `vp update -g` to move packages to the `latest` tag and clear their recorded specs. `vp outdated -g` reports both the newest version matching the recorded spec (`Wanted`) and the newest version on the `latest` tag.
+
 ::: warning
 These commands do **NOT** interact with the underlying package manager's global installation directory.
 

package/docs/guide/installer-env-vars.md

@@ -147,14 +147,14 @@ Vite+ sets additional `VP_*` variables during shim dispatch and shell integratio
 
 ## Logging and Debugging
 
-### `VITE_LOG`
+### `VP_LOG`
 
 - **Purpose**: Log filter string for `tracing_subscriber`
 - **Default**: None
 - **Example**:
   ```bash
-  VITE_LOG=debug vp dev
-  VITE_LOG=vite_task=trace vp build
+  VP_LOG=debug vp dev
+  VP_LOG=vite_task=trace vp build
   ```
 
 ### `VP_DEBUG_SHIM`

package/docs/guide/migrate.md

@@ -86,7 +86,7 @@ After the migration:
 Command mapping to keep in mind:
 
 - `vp run <script>` is the equivalent of `pnpm run <script>`
-- `vp test` runs the built-in test command, while `vp run test` runs the `test` script from `package.json`
+- `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
@@ -168,11 +168,19 @@ export default defineConfig({
 });
 ```
 
-After migrating, remove lint-staged from your dependencies and delete any lint-staged config files. 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](/guide/commit-hooks) and [Staged config reference](/config/staged) for details.
 
 ### Git hook tools
 
-The `vp migrate` command can set up Vite+ commit hooks for you, but it doesn't automatically migrate every type of Git hook tool. This automatic migration path is specifically designed to handle Husky v9+ and lint-staged-style setups. Projects using Husky versions older than 9.0.0 are skipped and should upgrade to Husky v9 before using the automatic migration path.
+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).
+
+Existing project-owned Vite+ hooks are also preserved. The default staged workflow is introduced
+only when no existing hook policy is found.
 
 If your project currently uses `lefthook`, `simple-git-hooks`, or `yorkie`, `vp migrate` will leave your existing configuration alone and show a warning. This happens even if you choose to set up hooks during the prompt or include the `--hooks` flag.
 

package/docs/guide/monorepo.md

@@ -145,16 +145,104 @@ This keeps the behavior centralized while letting each team or package own the p
 
 ## App Commands
 
-The root `vite.config.ts` is most valuable for shared linting, formatting, staged checks, and task definitions. For project-specific development, build, and test behavior, use the setup that best matches each app:
+The root `vite.config.ts` is most valuable for shared linting, formatting, staged checks, and task definitions. Development, build, preview, and packaging still act on a single app, so Vite+ makes the built-in commands monorepo-aware instead of forcing you to `cd` between packages.
 
-- Pass a folder to built-in Vite commands when you want to target one app:
+### Running at the workspace root
+
+`vp dev`, `vp build`, `vp preview`, and `vp pack` never silently act on the workspace root, which usually has no app of its own. Run them at the top of the monorepo and Vite+ works out which app you mean.
+
+When exactly one package looks like an app, vp runs it and shows you the direct command for next time:
+
+```
+$ vp dev
+Selected package: web (apps/web)
+Tip: run this directly with `vp -C apps/web dev`
+
+  VITE+ v0.2.2
+
+  ➜  Local:   http://localhost:5173/
+  ➜  Network: use --host to expose
+```
+
+When several packages could be the target, vp opens a fuzzy package picker (the same selector as `vp run`); typing filters, Enter runs the selection:
+
+```
+$ vp build
+Select a package to build (↑/↓, Enter to run, type to search):
+
+  › admin apps/admin
+    web   apps/web
+    ui    packages/ui
+```
+
+```
+Selected package: web (apps/web)
+Tip: run this directly with `vp -C apps/web build`
+
+  ✓ built in 187ms
+```
+
+In non-interactive shells (CI, pipes, redirection), vp prints the same packages as a plain listing with ready-to-copy commands and exits 1:
+
+```
+$ vp build | cat
+error: `vp build` at the workspace root needs a target package.
+
+  Packages in this workspace:
+    admin     apps/admin
+    web       apps/web
+    @shop/ui  packages/ui
+
+  Pass a directory:  vp -C apps/admin build
+  Or run every package's build script:  vp run -r build
+```
+
+vp ranks packages that look runnable for the command first in both the picker and the listing: a `vite.config.*` or root `index.html` for `dev` / `build` / `preview`, and a `pack` config block or tsdown's default `src/index.ts` entry for `pack`.
+
+### Targeting a package with `-C`
+
+The global `-C` flag runs any vp command as if you had `cd`'d into the package first, identical to `cd <dir> && vp <command>`:
 
 ```bash
-vp dev apps/web
-vp build apps/web
+vp -C apps/web dev
+vp -C apps/web build
+vp -C packages/ui pack
 ```
 
-- Keep package-specific scripts in each package when the command differs per app:
+Passing a folder as a positional (`vp dev apps/web`) still works, but keeps upstream Vite semantics: it sets Vite's `root` option without changing the working directory, so `process.cwd()` reads in configs and plugins resolve from where you ran vp. Prefer `-C` when the package should behave as if you had `cd`'d into it. When a directory positional is used, vp prints a one-line note pointing at the `-C` form.
+
+### A fixed default with `defaultPackage`
+
+To always target one directory and skip the resolution above, set [`defaultPackage`](/config/#defaultpackage) in the root config:
+
+```ts [vite.config.ts]
+export default {
+  defaultPackage: './apps/web',
+};
+```
+
+```
+$ vp dev
+note: vp dev: using ./apps/web (defaultPackage in vite.config.ts)
+
+  VITE+ v0.2.2
+
+  ➜  Local:   http://localhost:5173/
+```
+
+This is the right choice for framework monorepos that are not JavaScript workspaces, such as a Laravel or Rails app with a `frontend/` directory: there is no package list to resolve, so `defaultPackage` points vp straight at the app. Because vp reads it without executing the config, it works even when `vite-plus` is installed only inside that subdirectory.
+
+An object form maps commands individually, so `vp pack` can target a library while `vp dev` targets an app; a command absent from the object falls through to the resolution above:
+
+```ts [vite.config.ts]
+export default {
+  defaultPackage: { dev: './apps/web', pack: './packages/ui' },
+};
+```
+
+### Package scripts and workspace-wide tasks
+
+Keep package-specific scripts in each package when the command differs per app:
 
 ```json [apps/api/package.json]
 {
@@ -165,7 +253,7 @@ vp build apps/web
 }
 ```
 
-- Run scripts across the workspace with `vp run`:
+Run scripts across the whole workspace with `vp run`:
 
 ```bash
 vp run -r build

package/docs/guide/run.md

@@ -38,6 +38,21 @@ Select a task (↑/↓, Enter to run, Esc to clear):
     test: jest
 ```
 
+## Built-in Commands vs Scripts
+
+`vp dev` is a built-in command. `vp run dev` is your `dev` script. Built-in commands cannot be overwritten, so adding a `dev` script does not change what `vp dev` does:
+
+| Command                    | What it runs                                                              |
+| -------------------------- | ------------------------------------------------------------------------- |
+| `vp dev`                   | The built-in Vite dev server                                              |
+| `vp run dev` / `vpr dev`   | The `dev` script in `package.json`, or a `dev` task in `vite.config.ts`   |
+| `vp test`                  | The built-in Vitest command                                               |
+| `vp run test` / `vpr test` | The `test` script in `package.json`, or a `test` task in `vite.config.ts` |
+
+`build`, `preview`, `lint`, `fmt`, `check`, and `pack` work the same way.
+
+If the project defines that script or task, run it with `vp run <name>`. For example, with a `"dev": "astro dev"` script, `vp run dev` starts Astro, while `vp dev` ignores the script and starts Vite.
+
 ## Caching
 
 `package.json` scripts are not cached by default. Use `--cache` to enable caching:

package/docs/guide/test.md

@@ -6,6 +6,10 @@
 
 `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.
 
+::: info
+`vp test` always runs the built-in Vitest command. If your project also has a `test` script in `package.json`, run `vp run test` when you want to run that script instead. See [Built-in Commands vs Scripts](/guide/run#built-in-commands-vs-scripts).
+:::
+
 ## Usage
 
 ```bash

package/docs/guide/troubleshooting.md

@@ -31,15 +31,18 @@ If VS Code has multiple folders open, the shared Oxc language server may pick a
 
 - Confirm the extension is using the intended workspace.
 
-## `vp build` does not run my build script
+## `vp dev` or `vp build` does not run my script
 
-Unlike package managers, built-in commands cannot be overwritten. If you are trying to run a `package.json` script use `vp run build` instead.
+Unlike package managers, built-in commands cannot be overwritten. If you are trying to run a `package.json` script use `vp run <script>` instead.
 
 For example:
 
+- `vp dev` always starts the built-in Vite dev server
 - `vp build` always runs the built-in Vite build
 - `vp test` always runs the built-in Vitest command
-- `vp run build` and `vp run test` run `package.json` scripts instead
+- `vp run dev`, `vp run build`, and `vp run test` run the matching `package.json` scripts instead
+
+See [Built-in Commands vs Scripts](/guide/run#built-in-commands-vs-scripts) for when to prefer each path.
 
 ::: info
 You can also run custom tasks defined in `vite.config.ts` and migrate away from `package.json` scripts entirely.
@@ -50,8 +53,9 @@ You can also run custom tasks defined in `vite.config.ts` and migrate away from
 If `vp staged` fails or your pre-commit hook does not run:
 
 - make sure `vite.config.ts` contains a `staged` block
-- run `vp config` to install hooks
-- check whether hook installation was skipped intentionally through `VITE_GIT_HOOKS=0`
+- make sure the project-owned pre-commit hook runs `vp staged`
+- run `vp config` to install the hook dispatcher
+- check whether hook installation was skipped intentionally through `VP_GIT_HOOKS=0`
 
 A minimal staged config looks like this:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vite-plus",
-  "version": "0.2.6",
+  "version": "0.2.8",
   "description": "The Unified Toolchain for the Web",
   "homepage": "https://viteplus.dev/guide",
   "bugs": {
@@ -62,11 +62,6 @@
     "./bin": {
       "import": "./dist/bin.js"
     },
-    "./binding": {
-      "types": "./binding/index.d.cts",
-      "import": "./binding/index.cjs",
-      "require": "./binding/index.cjs"
-    },
     "./fmt": {
       "types": "./dist/fmt.d.ts",
       "import": "./dist/fmt.js"
@@ -352,7 +347,7 @@
     }
   },
   "dependencies": {
-    "@oxc-project/types": "=0.141.0",
+    "@oxc-project/types": "=0.142.0",
     "@oxlint/plugins": "=1.73.0",
     "@vitest/browser": "4.1.10",
     "@vitest/browser-preview": "4.1.10",
@@ -363,16 +358,17 @@
     "@vitest/snapshot": "4.1.10",
     "@vitest/spy": "4.1.10",
     "@vitest/utils": "4.1.10",
-    "oxfmt": "=0.60.0",
-    "oxlint": "=1.75.0",
+    "oxfmt": "=0.61.0",
+    "oxlint": "=1.76.0",
     "oxlint-tsgolint": "=7.0.2001",
     "vitest": "4.1.10",
-    "@voidzero-dev/vite-plus-core": "0.2.6"
+    "@voidzero-dev/vite-plus-core": "0.2.8"
   },
   "devDependencies": {
-    "@napi-rs/cli": "^3.7.3",
+    "@emnapi/core": "2.0.0-alpha.3",
+    "@emnapi/runtime": "2.0.0-alpha.3",
+    "@napi-rs/cli": "^3.8.2",
     "@nkzw/safe-word-list": "^3.1.0",
-    "@oxc-node/core": "^0.1.0",
     "@types/cross-spawn": "^6.0.6",
     "@types/semver": "^7.7.1",
     "@types/validate-npm-package-name": "^4.0.2",
@@ -390,15 +386,13 @@
     "mri": "^1.2.0",
     "nanotar": "^0.3.0",
     "picocolors": "^1.1.1",
-    "rolldown-plugin-dts": "^0.27.0",
     "semver": "^7.8.0",
-    "tsdown": "^0.22.13",
+    "tsdown": "^0.22.14",
     "validate-npm-package-name": "^7.0.2",
     "yaml": "^2.8.1",
     "zod": "^3.25.76",
     "@voidzero-dev/vite-plus-prompts": "0.0.0",
-    "vite": "npm:@voidzero-dev/vite-plus-core@0.2.6",
-    "@voidzero-dev/vite-plus-tools": "0.0.0"
+    "vite": "npm:@voidzero-dev/vite-plus-core@0.2.8"
   },
   "peerDependencies": {
     "@vitest/browser-playwright": "4.1.10",
@@ -430,14 +424,14 @@
     "node": "^20.19.0 || ^22.18.0 || >=24.11.0"
   },
   "optionalDependencies": {
-    "@voidzero-dev/vite-plus-darwin-arm64": "0.2.6",
-    "@voidzero-dev/vite-plus-darwin-x64": "0.2.6",
-    "@voidzero-dev/vite-plus-linux-arm64-gnu": "0.2.6",
-    "@voidzero-dev/vite-plus-linux-arm64-musl": "0.2.6",
-    "@voidzero-dev/vite-plus-linux-x64-gnu": "0.2.6",
-    "@voidzero-dev/vite-plus-linux-x64-musl": "0.2.6",
-    "@voidzero-dev/vite-plus-win32-x64-msvc": "0.2.6",
-    "@voidzero-dev/vite-plus-win32-arm64-msvc": "0.2.6"
+    "@voidzero-dev/vite-plus-darwin-arm64": "0.2.8",
+    "@voidzero-dev/vite-plus-darwin-x64": "0.2.8",
+    "@voidzero-dev/vite-plus-linux-arm64-gnu": "0.2.8",
+    "@voidzero-dev/vite-plus-linux-arm64-musl": "0.2.8",
+    "@voidzero-dev/vite-plus-linux-x64-gnu": "0.2.8",
+    "@voidzero-dev/vite-plus-linux-x64-musl": "0.2.8",
+    "@voidzero-dev/vite-plus-win32-x64-msvc": "0.2.8",
+    "@voidzero-dev/vite-plus-win32-arm64-msvc": "0.2.8"
   },
   "scripts": {
     "build": "oxnode -C dev ./build.ts",