Skip to main content
This page describes how the Aero framework repository manages dependency versions. If you are building an app with Aero, you normally use normal dependencies and devDependencies in your own package.json; this policy is mainly relevant for contributors and for understanding how Aero’s packages stay aligned.

​
pnpm catalog

Shared versions for framework development live in the root pnpm-workspace.yaml under catalog:. Packages reference them with the catalog: protocol in package.json (for example "vite": "catalog:"). Prefer catalog entries for tooling that should move together across packages (TypeScript, Vite, Vitest, Vitest UI, tsdown, Nitro, and @types/node).

​
Explicit versions

When a package needs a version different from the catalog (for example a single package requires a newer patch), use an explicit semver range in that package’s package.json and prefer a short note in the PR if the reason is not obvious.

​
Root overrides

The root package.json may define pnpm.overrides for security fixes or to align a transitive dependency with a known-good version. Treat overrides as explicit exceptions — document why in the commit or a short comment when non-obvious. Current root overrides in pnpm-workspace.yaml:
  • js-yaml: ^3.15.0 — patches a moderate CVE in gray-matter’s transitive js-yaml 3.x without jumping to js-yaml 4 (which breaks gray-matter’s CommonJS require path).
  • nf3: 0.4.2 — Nitro 3 pulls nf3 for production dependency tracing; 0.3.x ESM-imports @vercel/nft in a way that fails on Node 22 until 0.4.x bundles NFT. Required for full-stack kitchen-sink / server: true Nitro builds.
Previously removed overrides (vite, nitro, brace-expansion) were redundant with catalog + lockfile once duplicate exact pins were consolidated.

​
Peer dependency ranges

Published packages use semver ranges for optional peers (for example "vite": "^8.1.0"), not exact pins. Starter template package.json files under packages/create/templates/* use semver for @aero-js/core and pin Vite+ via pnpm.overrides for standalone clones.

​
Manual refresh checklist

When bumping dependencies across the monorepo:
  1. Consolidate pins first — prefer catalog: over hardcoded versions; remove redundant pnpm.overrides.
  2. Bump in tiers — low-risk utilities, then catalog toolchain (vite, nitro, typescript, vitest, tsdown), then one ecosystem per PR (oxc, shiki, volar, etc.).
  3. Sync starter templates — packages/create/templates/*/package.json vite/nitro/vite-plus pins must match catalog policy.
  4. Regenerate lockfile — pnpm install after every manifest edit.
  5. Validate locally — run vp run check:all, not vp run release:prep alone. Before merging large toolchain bumps, run vp run build:website.

​
CI and guardrails

  • pnpm install with a locked lockfile is the source of truth for CI.
  • Keep packageManager in root package.json aligned with the pnpm version contributors should use.
For product-level principles that include staying aligned with Vite and modern JS tooling, see Aero principles and goals.