|
| 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--> |
| 89 | + |
| 90 | +<!--injected-by-void-v0.2.3--> |
| 91 | + |
| 92 | +## Void |
| 93 | + |
| 94 | +This project uses [Void](https://void.cloud) — a fullstack Vite plugin + deployment platform for Cloudflare. `voidPlugin()` in `vite.config.ts` gives you file-based API routing on Hono (`routes/`), Inertia-inspired server-rendered pages with co-located loaders/actions (`pages/` + `@void/vue` or `@void/react`), auto-provisioned D1/KV/R2 bindings, first-class Drizzle ORM integration (schema in `db/schema.ts` -> `void/db` Drizzle instance -> typed routes -> typed fetch client), built-in auth, queues, cron jobs, edge caching (ISR), and one-command deploys via `npx void deploy`. For first-time setup, prefer `npx void init`; the interactive flow can scaffold the app, configure project files, handle auth, and link or create the deploy project before the first deploy. During the private beta, installation may use GitHub Packages aliases such as `void@npm:@void-sdk/void`, but source imports stay on `void` and `@void/*`. The checked-in project `.npmrc` should only contain `@void-sdk:registry=https://npm.pkg.github.com`; installation auth belongs in the user's `~/.npmrc` via `//npm.pkg.github.com/:_authToken=YOUR_GITHUB_PAT` using a classic GitHub PAT with `read:packages`. |
| 95 | + |
| 96 | +Database: define Drizzle tables in `db/schema.ts`, import `db` from `void/db` and tables from `@schema`. Use `void db push` for prototyping, `void db generate` for production migrations. `drizzle-orm` and `drizzle-kit` ship with void (no extra install). Migrations live in `db/migrations/`. |
| 97 | + |
| 98 | +Full docs are in `node_modules/void/docs/`. If you have the `void` skill available, use it for a complete API reference covering project structure, routing, pages mode, database, auth, typed fetch, KV, storage, queues, cron jobs, CLI, configuration, and deployment. |
| 99 | + |
| 100 | +<!--/injected-by-void--> |
0 commit comments