CodeVetter · Repo Unpack · Contributor handoff
vitejs/vite
This is a high-traffic OSS monorepo with strict conventions: pnpm only (enforced by `only-allow` in `preinstall`), oxfmt for formatting, eslint for `packages/*/{src,types}/**/*.ts`, and a `simple-git-hooks` pre-commit running lint-staged. Almost nothing can be verified without first running `pnpm build`, since the playground tests execute the built `dist/node/cli.js`. Read the CLI, server bootstrap, config resolver, and plugin pipeline before touching anything; treat the security guards and the deprecation shims as append-only unless the change is deliberate. The most common trap is editing `packages/vite/src/node` and testing without rebuilding, or adding a runtime dependency to the wrong section of `package.json`.
- Read first, in order: `packages/vite/src/node/cli.ts` (command surface), `packages/vite/src/node/server/index.ts` (`_createServer` + middleware order), `packages/vite/src/node/config.ts` (`resolveConfig`, `loadConfigFromFile`), `packages/vite/src/node/plugins/index.ts` (`resolvePlugins` ordering) and `packages/vite/src/node/build.ts` (`createBuilder`/`buildEnvironment`).
- Setup is `pnpm i` then `pnpm run build` at the repo root; while developing Vite itself, run `pnpm run dev` inside `packages/vite` for a watching Rolldown rebuild (`premove dist && pnpm build-bundle -w`).
- pnpm is mandatory — root `preinstall` runs `npx only-allow pnpm` and `packageManager` pins `pnpm@12.4.2`; npm/yarn installs will be rejected.
- Verification commands: `pnpm test-unit` (fast, no browser), `pnpm test-serve [match]` / `pnpm test-build [match]` for targeted playground runs, `pnpm lint`, `pnpm format` (oxfmt), and `pnpm typecheck` (root `tsc -p scripts` plus every package's own typecheck).
- Playground test matching is per-substring and only works on `test-serve`/`test-build`, not on `pnpm test` — e.g. `pnpm run test-serve assets` runs both `playground/assets` and `playground/assets-sanitize`.
- Trap: playground tests run against a real `vite` binary resolved through `viteBinPath` in `vitestSetup.ts`, so source edits in `packages/vite/src` are invisible to integration tests until `pnpm build` (or a running `pnpm dev` watcher) regenerates `dist`.
- Trap: the e2e global setup copies playgrounds into `playground-temp/` and only copies the directories matched by the selected spec files — a new fixture directory that no spec references will not be copied, and `VITE_PRESERVE_BUILD_ARTIFACTS=1` (via `pnpm debug-build`) is needed to inspect the output.
- Dependency placement is a reviewed decision: `packages/vite/package.json` carries a literal `"//": "READ CONTRIBUTING.md to understand what to put under deps vs. devDeps!"` marker, and CONTRIBUTING has sections on `require()` usage, adding dependencies, and ensuring type support.
- Formatting and linting are enforced on commit: `simple-git-hooks` pre-commit runs `lint-staged --concurrent false`, which applies `oxfmt` to all files and eslint `--fix` to `packages/*/{src,types}/**/*.ts`, `packages/**/*.d.ts` and `playground/**/__tests__/**/*.ts`.
- Safe edit boundary: anything under `playground/` is fixture + spec code, not shipped code — only `packages/vite`, `packages/create-vite` and `packages/plugin-legacy` are published, and CI skips tests entirely for `packages/create-vite/template**` changes.
- Do not relax the filesystem guards casually: `isFileLoadingAllowed`, `looksLikeWindowsShortNamePath`, the NTFS-colon check and `rejectInvalidRequestMiddleware` each carry comments identifying a specific bypass class they exist to block.
- When adding a server-facing API, mirror the environment convention: put state on `DevEnvironment` (which owns `moduleGraph`, `pluginContainer`, `_pendingRequests`, `transformRequest`, `warmupRequest`, `waitForRequestsIdle`) and expose any flat `server.*` alias only through `warnFutureDeprecation`.
- Debug logging convention: use `createDebugger('vite:<area>')` (e.g. `vite:load`, `vite:transform`, `vite:cache`, `vite:env`, `vite:hmr`) and keep middleware functions *named*, since the names surface under `DEBUG=connect:dispatcher` — several files carry that exact comment.
- Releases are automated and should not be hand-driven: `publish.yml` runs `scripts/detect-release.ts` against the latest commit subject on pushes to `main`/`v[0-9]*`, and `pnpm ci-publish` invokes `scripts/publishCI.ts`; `prepare-release.yml` and `scripts/prepare-release.ts` handle version bumps.
- The repo has an explicit AI Policy section in CONTRIBUTING.md alongside the Pull Request Guidelines and issue-triaging workflow — read it before opening a PR from an agent-assisted change.