vite-plus 0.1.13 → 0.1.14-alpha.0

package/skills/vite-plus/docs/guide/install.md

@@ -0,0 +1,130 @@
+# Installing Dependencies
+
+`vp install` installs dependencies using the current workspace's package manager.
+
+## Overview
+
+Use Vite+ to manage dependencies across pnpm, npm, and Yarn. Instead of switching between `pnpm install`, `npm install`, and `yarn install`, you can keep using `vp install`, `vp add`, `vp remove`, and the rest of the Vite+ package-management commands.
+
+Vite+ detects the package manager from the workspace root in this order:
+
+1. `packageManager` in `package.json`
+2. `pnpm-workspace.yaml`
+3. `pnpm-lock.yaml`
+4. `yarn.lock` or `.yarnrc.yml`
+5. `package-lock.json`
+6. `.pnpmfile.cjs` or `pnpmfile.cjs`
+7. `yarn.config.cjs`
+
+If none of those files are present, `vp` falls back to `pnpm` by default. Vite+ automatically downloads the matching package manager and uses it for the command you ran.
+
+## Usage
+
+```bash
+vp install
+```
+
+Common install flows:
+
+```bash
+vp install
+vp install --frozen-lockfile
+vp install --lockfile-only
+vp install --filter web
+vp install -w
+```
+
+`vp install` maps to the correct underlying install behavior for the detected package manager, including the right lockfile flags for pnpm, npm, and Yarn.
+
+## Global Packages
+
+Use the `-g` flag for installing, updating or removing globally installed packages:
+
+- `vp install -g <pkg>` installs a package globally
+- `vp uninstall -g <pkg>` removes a global package
+- `vp update -g [pkg]` updates one global package or all of them
+- `vp list -g [pkg]` lists global packages
+
+## Managing Dependencies
+
+Vite+ provides all the familiar package management commands:
+
+- `vp install` installs the current dependency graph for the project
+- `vp add <pkg>` adds packages to `dependencies`, use `-D` for `devDependencies`
+- `vp remove <pkg>` removes packages
+- `vp update` updates dependencies
+- `vp dedupe` reduces duplicate dependency entries where the package manager supports it
+- `vp outdated` shows available updates
+- `vp list` shows installed packages
+- `vp why <pkg>` explains why a package is present
+- `vp info <pkg>` shows registry metadata for a package
+- `vp link` and `vp unlink` manage local package links
+- `vp dlx <pkg>` runs a package binary without adding it to the project
+- `vp pm <command>` forwards a raw package-manager-specific command when you need behavior outside the normalized `vp` command set
+
+### Command Guide
+
+#### Install
+
+Use `vp install` when you want to install exactly what the current `package.json` and lockfile describe.
+
+- `vp install` is the standard install command
+- `vp install --frozen-lockfile` fails if the lockfile would need changes
+- `vp install --no-frozen-lockfile` allows lockfile updates explicitly
+- `vp install --lockfile-only` updates the lockfile without performing a full install
+- `vp install --prefer-offline` and `vp install --offline` prefer or require cached packages
+- `vp install --ignore-scripts` skips lifecycle scripts
+- `vp install --filter <pattern>` scopes install work in monorepos
+- `vp install -w` installs in the workspace root
+
+#### Global Install
+
+Use these commands when you want package-manager-managed tools available outside a single project.
+
+- `vp install -g typescript`
+- `vp uninstall -g typescript`
+- `vp update -g`
+- `vp list -g`
+
+#### Add and Remove
+
+Use `vp add` and `vp remove` for day-to-day dependency edits instead of editing `package.json` by hand.
+
+- `vp add react`
+- `vp add -D typescript vitest`
+- `vp add -O fsevents`
+- `vp add --save-peer react`
+- `vp remove react`
+- `vp remove --filter web react`
+
+#### Update, Dedupe, and Outdated
+
+Use these commands to maintain the dependency graph over time.
+
+- `vp update` refreshes packages to newer versions
+- `vp outdated` shows which packages have newer versions available
+- `vp dedupe` asks the package manager to collapse duplicates where possible
+
+#### Inspect
+
+Use these when you need to understand the current state of dependencies.
+
+- `vp list` shows installed packages
+- `vp why react` explains why `react` is installed
+- `vp info react` shows registry metadata such as versions and dist-tags
+
+#### Advanced
+
+Use these when you need lower-level package-manager behavior.
+
+- `vp link` and `vp unlink` manage local development links
+- `vp dlx create-vite` runs a package binary without saving it as a dependency
+- `vp pm <command>` forwards directly to the resolved package manager
+
+Examples:
+
+```bash
+vp pm config get registry
+vp pm cache clean --force
+vp pm exec tsc --version
+```

package/skills/vite-plus/docs/guide/lint.md

@@ -0,0 +1,50 @@
+# Lint
+
+`vp lint` lints code with Oxlint.
+
+## Overview
+
+`vp lint` is built on [Oxlint](https://oxc.rs/docs/guide/usage/linter.html), the Oxc linter. Oxlint is designed as a fast replacement for ESLint for most frontend projects and ships with built-in support for core ESLint rules and many popular community rules.
+
+Use `vp lint` to lint your project, and `vp check` to format, lint and type-check all at once.
+
+## Usage
+
+```bash
+vp lint
+vp lint --fix
+vp lint --type-aware
+```
+
+## Configuration
+
+Put lint configuration directly in the `lint` block in `vite.config.ts` so all your configuration stays in one place. We do not recommend using `oxlint.config.ts` or `.oxlintrc.json` with Vite+.
+
+For the upstream rule set, options, and compatibility details, see the [Oxlint docs](https://oxc.rs/docs/guide/usage/linter.html).
+
+```ts
+import { defineConfig } from 'vite-plus';
+
+export default defineConfig({
+  lint: {
+    ignorePatterns: ['dist/**'],
+    options: {
+      typeAware: true,
+      typeCheck: true,
+    },
+  },
+});
+```
+
+## Type-Aware Linting
+
+We recommend enabling both `typeAware` and `typeCheck` in the `lint` block:
+
+- `typeAware: true` enables rules that require TypeScript type information
+- `typeCheck: true` enables full type checking during linting
+
+This path is powered by [tsgolint](https://github.com/oxc-project/tsgolint) on top of the TypeScript Go toolchain. It gives Oxlint access to type information and allows type checking directly via `vp lint` and `vp check`.
+
+## JS Plugins
+
+If you are migrating from ESLint and still depend on a few critical JavaScript-based ESLint plugins, Oxlint has [JS plugin support](https://oxc.rs/docs/guide/usage/linter/js-plugins) that can help you keep those plugins running while you complete the migration.

package/skills/vite-plus/docs/guide/migrate.md

@@ -0,0 +1,174 @@
+# 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, and Prettier 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.
+
+## Usage
+
+```bash
+vp migrate
+vp migrate <path>
+vp migrate --no-interactive
+```
+
+## Target Path
+
+The positional `PATH` argument is optional.
+
+- If omitted, `vp migrate` migrates the current directory
+- If provided, it migrates that target directory instead
+
+```bash
+vp migrate
+vp migrate my-app
+```
+
+## Options
+
+- `--agent <name>` writes agent instructions into the project
+- `--no-agent` skips agent instruction setup
+- `--editor <name>` writes editor config files into the project
+- `--no-editor` skips editor config setup
+- `--hooks` sets up pre-commit hooks
+- `--no-hooks` skips hook setup
+- `--no-interactive` runs the migration without prompts
+
+## Migration Flow
+
+The `migrate` command is designed to move existing projects onto Vite+ quickly. Here is what the command does:
+
+- Updates project dependencies
+- Rewrites imports where needed
+- Merges tool-specific config into `vite.config.ts`
+- Updates scripts to the Vite+ command surface
+- Can set up commit hooks
+- Can write agent and editor configuration files
+
+Most projects will require further manual adjustments after running `vp migrate`.
+
+## Recommended Workflow
+
+Before running the migration:
+
+- 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:
+
+- Run `vp install`
+- Run `vp check`
+- Run `vp test`
+- Run `vp build`
+
+## Migration Prompt
+
+If you want to hand this work to a coding agent (or the reader is a coding agent!), use this migration prompt:
+
+```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.
+
+After the migration:
+
+- Confirm `vite` imports were rewritten to `vite-plus` where needed
+- Confirm `vitest` imports were rewritten to `vite-plus/test` where needed
+- Remove old `vite` and `vitest` dependencies only after those rewrites are confirmed
+- Move remaining tool-specific config into the appropriate blocks in `vite.config.ts`
+
+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 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
+
+Finally, verify the migration by running: `vp install`, `vp check`, `vp test`, and `vp build`
+
+Summarize the migration at the end and report any manual follow-up still required.
+```
+
+## Tool-Specific Migrations
+
+### Vitest
+
+Vitest is automatically migrated through `vp migrate`. If you are migrating manually, you have to update all the imports to `vite-plus/test` instead:
+
+```ts
+// before
+import { describe, expect, it, vi } from 'vitest';
+
+const { page } = await import('@vitest/browser/context');
+
+// after
+import { describe, expect, it, vi } from 'vite-plus/test';
+
+const { page } = await import('vite-plus/test/browser/context');
+```
+
+### tsdown
+
+If your project uses a `tsdown.config.ts`, move its options into the `pack` block in `vite.config.ts`:
+
+```ts
+// before — tsdown.config.ts
+import { defineConfig } from 'tsdown';
+
+export default defineConfig({
+  entry: ['src/index.ts'],
+  dts: true,
+  format: ['esm', 'cjs'],
+});
+
+// after — vite.config.ts
+import { defineConfig } from 'vite-plus';
+
+export default defineConfig({
+  pack: {
+    entry: ['src/index.ts'],
+    dts: true,
+    format: ['esm', 'cjs'],
+  },
+});
+```
+
+After merging, delete `tsdown.config.ts`. See the [Pack guide](/guide/pack) for the full configuration reference.
+
+### lint-staged
+
+Vite+ replaces lint-staged with its own `staged` block in `vite.config.ts`. Only the `staged` config format is supported. Standalone `.lintstagedrc` in non-JSON format and `lint-staged.config.*` are not migrated automatically.
+
+Move your lint-staged rules into the `staged` block:
+
+```ts
+// vite.config.ts
+import { defineConfig } from 'vite-plus';
+
+export default defineConfig({
+  staged: {
+    '*.{js,ts,tsx,vue,svelte}': 'vp check --fix',
+  },
+});
+```
+
+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.
+
+## Examples
+
+```bash
+# Migrate the current project
+vp migrate
+
+# Migrate a specific directory
+vp migrate my-app
+
+# Run without prompts
+vp migrate --no-interactive
+
+# Write agent and editor setup during migration
+vp migrate --agent claude --editor zed
+```

package/skills/vite-plus/docs/guide/pack.md

@@ -0,0 +1,61 @@
+# Pack
+
+`vp pack` builds libraries for production with [tsdown](https://tsdown.dev/guide/).
+
+## Overview
+
+`vp pack` builds libraries and standalone executables with tsdown. Use it for publishable packages and binary outputs. If you want to build a web application, use `vp build`. `vp pack` covers everything you need for building libraries out of the box, including declaration file generation, multiple output formats, source maps, and minification.
+
+For more information about how tsdown works, see the official [tsdown guide](https://tsdown.dev/guide/).
+
+## Usage
+
+```bash
+vp pack
+vp pack src/index.ts --dts
+vp pack --watch
+```
+
+## Configuration
+
+Put packaging configuration directly in the `pack` block in `vite.config.ts` so all your configuration stays in one place. We do not recommend using `tsdown.config.ts` with Vite+.
+
+See the [tsdown guide](https://tsdown.dev/guide/) and the [tsdown config file docs](https://tsdown.dev/options/config-file) to learn more about how to use and configure `vp pack`.
+
+Use it for:
+
+- [declaration files (`dts`)](https://tsdown.dev/options/dts)
+- [output formats](https://tsdown.dev/options/output-format)
+- [watch mode](https://tsdown.dev/options/watch-mode)
+- [standalone executables](https://tsdown.dev/options/exe#executable)
+
+```ts
+import { defineConfig } from 'vite-plus';
+
+export default defineConfig({
+  pack: {
+    dts: true,
+    format: ['esm', 'cjs'],
+    sourcemap: true,
+  },
+});
+```
+
+## Standalone Executables
+
+`vp pack` can also build standalone executables through tsdown's experimental [`exe` option](https://tsdown.dev/options/exe#executable).
+
+Use this when you want to ship a CLI or other Node-based tool as a native executable that runs without requiring Node.js to be installed separately.
+
+```ts
+import { defineConfig } from 'vite-plus';
+
+export default defineConfig({
+  pack: {
+    entry: ['src/cli.ts'],
+    exe: true,
+  },
+});
+```
+
+See the official [tsdown executable docs](https://tsdown.dev/options/exe#executable) for details about configuring custom file names, embedded assets, and cross-platform targets.

package/skills/vite-plus/docs/guide/run.md

@@ -0,0 +1,292 @@
+# Run
+
+`vp run` runs `package.json` scripts and tasks defined in `vite.config.ts`. It works like `pnpm run`, with caching, dependency ordering, and workspace-aware execution built in.
+
+## Overview
+
+Use `vp run` with existing `package.json` scripts:
+
+```json [package.json]
+{
+  "scripts": {
+    "build": "node compile-legacy-app.js",
+    "test": "jest"
+  }
+}
+```
+
+`vp run build` executes the associated build script:
+
+```
+$ node compile-legacy-app.js
+
+building legacy app for production...
+
+✓ built in 69s
+```
+
+Use `vp run` without a task name to use the interactive task runner:
+
+```
+Select a task (↑/↓, Enter to run, Esc to clear):
+
+  › build: node compile-legacy-app.js
+    test: jest
+```
+
+## Caching
+
+`package.json` scripts are not cached by default. Use `--cache` to enable caching:
+
+```bash
+vp run --cache build
+```
+
+```
+$ node compile-legacy-app.js
+✓ built in 69s
+```
+
+If nothing changes, the output is replayed from the cache on the next run:
+
+```
+$ node compile-legacy-app.js ✓ cache hit, replaying
+✓ built in 69s
+
+---
+vp run: cache hit, 69s saved.
+```
+
+If an input changes, the task runs again:
+
+```
+$ node compile-legacy-app.js ✗ cache miss: 'legacy/index.js' modified, executing
+```
+
+## Task Definitions
+
+Vite Task automatically tracks which files your command uses. You can define tasks directly in `vite.config.ts` to enable caching by default or control which files and environment variables affect cache behavior.
+
+```ts
+import { defineConfig } from 'vite-plus';
+
+export default defineConfig({
+  run: {
+    tasks: {
+      build: {
+        command: 'vp build',
+        dependsOn: ['lint'],
+        env: ['NODE_ENV'],
+      },
+      deploy: {
+        command: 'deploy-script --prod',
+        cache: false,
+        dependsOn: ['build', 'test'],
+      },
+    },
+  },
+});
+```
+
+If you want to run an existing `package.json` script as-is, use `vp run <script>`. If you want task-level caching, dependencies, or environment/input controls, define a task with an explicit `command`. A task name can come from `vite.config.ts` or `package.json`, but not both.
+
+::: info
+Tasks defined in `vite.config.ts` are cached by default. `package.json` scripts are not. See [When Is Caching Enabled?](/guide/cache#when-is-caching-enabled) for the full resolution order.
+:::
+
+See [Run Config](/config/run) for the full `run` block reference.
+
+## Task Dependencies
+
+Use [`dependsOn`](#depends-on) to run tasks in the right order. Running `vp run deploy` with the config above runs `build` and `test` first. Dependencies can also target other packages in the same project with the `package#task` notation:
+
+```ts
+dependsOn: ['@my/core#build', '@my/utils#lint'];
+```
+
+## Running in a Workspace
+
+With no package-selection flags, `vp run` runs the task in the package in your current working directory:
+
+```bash
+cd packages/app
+vp run build
+```
+
+You can also target a package explicitly from anywhere:
+
+```bash
+vp run @my/app#build
+```
+
+Workspace package ordering is based on the normal monorepo dependency graph declared in each package's `package.json`. In other words, when Vite+ talks about package dependencies, it means the regular `dependencies` relationships between workspace packages, not a separate task-runner-specific graph.
+
+### Recursive (`-r`)
+
+Run the task in every workspace package, in dependency order:
+
+```bash
+vp run -r build
+```
+
+That dependency order comes from the workspace packages referenced through `package.json` dependencies.
+
+### Transitive (`-t`)
+
+Run the task in one package and all of its dependencies:
+
+```bash
+vp run -t @my/app#build
+```
+
+If `@my/app` depends on `@my/utils`, which depends on `@my/core`, this runs all three in order. Vite+ resolves that chain from the normal workspace package dependencies declared in `package.json`.
+
+### Filter (`--filter`)
+
+Select packages by name, directory, or glob pattern. The syntax matches pnpm's `--filter`:
+
+```bash
+# By name
+vp run --filter @my/app build
+
+# By glob
+vp run --filter "@my/*" build
+
+# By directory
+vp run --filter ./packages/app build
+
+# Include dependencies
+vp run --filter "@my/app..." build
+
+# Include dependents
+vp run --filter "...@my/core" build
+
+# Exclude packages
+vp run --filter "@my/*" --filter "!@my/utils" build
+```
+
+Multiple `--filter` flags are combined as a union. Exclusion filters are applied after all inclusions.
+
+### Workspace Root (`-w`)
+
+Explicitly run the task in the workspace root package:
+
+```bash
+vp run -w build
+```
+
+## Compound Commands
+
+Commands joined with `&&` are split into independent sub-tasks. Each sub-task is cached separately when [caching is enabled](/guide/cache#when-is-caching-enabled). This works for both `vite.config.ts` tasks and `package.json` scripts:
+
+```json [package.json]
+{
+  "scripts": {
+    "check": "vp lint && vp build"
+  }
+}
+```
+
+Now, run `vp run --cache check`:
+
+```
+$ vp lint
+Found 0 warnings and 0 errors.
+
+$ vp build
+✓ built in 28ms
+
+---
+vp run: 0/2 cache hit (0%).
+```
+
+Each sub-task has its own cache entry. If only `.ts` files changed but lint still passes, only `vp build` runs again the next time `vp run --cache check` is called:
+
+```
+$ vp lint ✓ cache hit, replaying
+$ vp build ✗ cache miss: 'src/index.ts' modified, executing
+✓ built in 30ms
+
+---
+vp run: 1/2 cache hit (50%), 120ms saved.
+```
+
+### Nested `vp run`
+
+When a command contains `vp run`, Vite Task inlines it as separate tasks instead of spawning a nested process. Each sub-task is cached independently and output stays flat:
+
+```json [package.json]
+{
+  "scripts": {
+    "ci": "vp run lint && vp run test && vp run build"
+  }
+}
+```
+
+Running `vp run ci` expands into three tasks:
+
+```mermaid
+graph LR
+  lint --> test --> build
+```
+
+Flags also work inside nested scripts. For example, `vp run -r build` inside a script expands into individual build tasks for every package.
+
+::: info
+A common monorepo pattern is a root script that runs a task recursively:
+
+```json [package.json (root)]
+{
+  "scripts": {
+    "build": "vp run -r build"
+  }
+}
+```
+
+This creates a potential recursion: root's `build` -> `vp run -r build` -> includes root's `build` -> ...
+
+Vite Task detects this and prunes the self-reference automatically, so other packages build normally.
+:::
+
+## Execution Summary
+
+Use `-v` to show a detailed execution summary:
+
+```bash
+vp run -r -v build
+```
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+    Vite+ Task Runner • Execution Summary
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Statistics:   3 tasks • 3 cache hits • 0 cache misses
+Performance:  100% cache hit rate, 468ms saved in total
+
+Task Details:
+────────────────────────────────────────────────
+  [1] @my/core#build: ~/packages/core$ vp build ✓
+      → Cache hit - output replayed - 200ms saved
+  ·······················································
+  [2] @my/utils#build: ~/packages/utils$ vp build ✓
+      → Cache hit - output replayed - 150ms saved
+  ·······················································
+  [3] @my/app#build: ~/packages/app$ vp build ✓
+      → Cache hit - output replayed - 118ms saved
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+Use `--last-details` to show the summary from the last run without running tasks again:
+
+```bash
+vp run --last-details
+```
+
+## Additional Arguments
+
+Arguments after the task name are passed through to the task command:
+
+```bash
+vp run test --reporter verbose
+```