|
| 1 | +<!--VITE PLUS START--> |
| 2 | + |
| 3 | +# Using Vite+, the Unified Toolchain for the Web |
| 4 | + |
| 5 | +This project is using Vite+, a unified toolchain built on top of Vite, Rolldown, Vitest, tsdown, Oxlint, Oxfmt, and Vite Task. Vite+ wraps runtime management, package management, and frontend tooling in a single global CLI called `vp`. Vite+ is distinct from Vite, but it invokes Vite through `vp dev` and `vp build`. |
| 6 | + |
| 7 | +## Vite+ Workflow |
| 8 | + |
| 9 | +`vp` is a global binary that handles the full development lifecycle. Run `vp help` to print a list of commands and `vp <command> --help` for information about a specific command. |
| 10 | + |
| 11 | +### Start |
| 12 | + |
| 13 | +- create - Create a new project from a template |
| 14 | +- migrate - Migrate an existing project to Vite+ |
| 15 | +- config - Configure hooks and agent integration |
| 16 | +- staged - Run linters on staged files |
| 17 | +- install (`i`) - Install dependencies |
| 18 | +- env - Manage Node.js versions |
| 19 | + |
| 20 | +### Develop |
| 21 | + |
| 22 | +- dev - Run the development server |
| 23 | +- check - Run format, lint, and TypeScript type checks |
| 24 | +- lint - Lint code |
| 25 | +- fmt - Format code |
| 26 | +- test - Run tests |
| 27 | + |
| 28 | +### Execute |
| 29 | + |
| 30 | +- run - Run monorepo tasks |
| 31 | +- exec - Execute a command from local `node_modules/.bin` |
| 32 | +- dlx - Execute a package binary without installing it as a dependency |
| 33 | +- cache - Manage the task cache |
| 34 | + |
| 35 | +### Build |
| 36 | + |
| 37 | +- build - Build for production |
| 38 | +- pack - Build libraries |
| 39 | +- preview - Preview production build |
| 40 | + |
| 41 | +### Manage Dependencies |
| 42 | + |
| 43 | +Vite+ automatically detects and wraps the underlying package manager such as pnpm, npm, or Yarn through the `packageManager` field in `package.json` or package manager-specific lockfiles. |
| 44 | + |
| 45 | +- add - Add packages to dependencies |
| 46 | +- remove (`rm`, `un`, `uninstall`) - Remove packages from dependencies |
| 47 | +- update (`up`) - Update packages to latest versions |
| 48 | +- dedupe - Deduplicate dependencies |
| 49 | +- outdated - Check for outdated packages |
| 50 | +- list (`ls`) - List installed packages |
| 51 | +- why (`explain`) - Show why a package is installed |
| 52 | +- info (`view`, `show`) - View package information from the registry |
| 53 | +- link (`ln`) / unlink - Manage local package links |
| 54 | +- pm - Forward a command to the package manager |
| 55 | + |
| 56 | +### Maintain |
| 57 | + |
| 58 | +- upgrade - Update `vp` itself to the latest version |
| 59 | + |
| 60 | +These commands map to their corresponding tools. For example, `vp dev --port 3000` runs Vite's dev server and works the same as Vite. `vp test` runs JavaScript tests through the bundled Vitest. The version of all tools can be checked using `vp --version`. This is useful when researching documentation, features, and bugs. |
| 61 | + |
| 62 | +## Common Pitfalls |
| 63 | + |
| 64 | +- **Using the package manager directly:** Do not use pnpm, npm, or Yarn directly. Vite+ can handle all package manager operations. |
| 65 | +- **Always use Vite commands to run tools:** Don't attempt to run `vp vitest` or `vp oxlint`. They do not exist. Use `vp test` and `vp lint` instead. |
| 66 | +- **Running scripts:** Vite+ built-in commands (`vp dev`, `vp build`, `vp test`, etc.) always run the Vite+ built-in tool, not any `package.json` script of the same name. To run a custom script that shares a name with a built-in command, use `vp run <script>`. For example, if you have a custom `dev` script that runs multiple services concurrently, run it with `vp run dev`, not `vp dev` (which always starts Vite's dev server). |
| 67 | +- **Do not install Vitest, Oxlint, Oxfmt, or tsdown directly:** Vite+ wraps these tools. They must not be installed directly. You cannot upgrade these tools by installing their latest versions. Always use Vite+ commands. |
| 68 | +- **Use Vite+ wrappers for one-off binaries:** Use `vp dlx` instead of package-manager-specific `dlx`/`npx` commands. |
| 69 | +- **Import JavaScript modules from `vite-plus`:** Instead of importing from `vite` or `vitest`, all modules should be imported from the project's `vite-plus` dependency. For example, `import { defineConfig } from 'vite-plus';` or `import { expect, test, vi } from 'vite-plus/test';`. You must not install `vitest` to import test utilities. |
| 70 | +- **Type-Aware Linting:** There is no need to install `oxlint-tsgolint`, `vp lint --type-aware` works out of the box. |
| 71 | + |
| 72 | +## CI Integration |
| 73 | + |
| 74 | +For GitHub Actions, consider using [`voidzero-dev/setup-vp`](https://github.com/voidzero-dev/setup-vp) to replace separate `actions/setup-node`, package-manager setup, cache, and install steps with a single action. |
| 75 | + |
| 76 | +```yaml |
| 77 | +- uses: voidzero-dev/setup-vp@v1 |
| 78 | + with: |
| 79 | + cache: true |
| 80 | +- run: vp check |
| 81 | +- run: vp test |
| 82 | +``` |
| 83 | +
|
| 84 | +## Review Checklist for Agents |
| 85 | +
|
| 86 | +- [ ] Run `vp install` after pulling remote changes and before getting started. |
| 87 | +- [ ] Run `vp check` and `vp test` to validate changes. |
| 88 | +<!--VITE PLUS END--> |
0 commit comments