← knowledge.oriz.in

Always install the latest version of every dependency

rule rulepnpmdependenciesversioningno-quotas

Always install the latest version of every dependency

The rule

When you add a new dependency to any oriz repo, install the latest published version. When you refresh existing deps, bump them to the latest minor / major unless an explicit pin is documented.

This is a family-wide rule, not a per-repo opinion. Old deps eventually reach end-of-life, lose security patches, or get migrated to paid tiers — all of which conflict with the never-hit-quotas and no-card-on-file stance. Stay current.

Install commands

For new dependencies, always include the @latest tag:

# Correct
pnpm add astro@latest
pnpm add -D vitest@latest

# Wrong — pnpm may resolve to whatever the local cache thinks is current,
# which can be stale by months on a dev machine that hasn't refreshed in a while
pnpm add astro

The @latest tag forces pnpm to consult the registry and pick the newest version, ignoring the local cache for resolution (it still reuses cached tarballs once it knows the version).

Update commands

Refresh dependencies on a regular cadence — weekly is the floor:

# Update every package in every workspace to the latest version,
# including major bumps
pnpm update --latest --recursive

# Inside a single repo (no workspace)
pnpm update --latest

Run the test suite + typecheck after every refresh. Major bumps sometimes break — that's fine, fix forward, don't pin backward.

Catalog dependencies (monorepos with pnpm-workspace.yaml)

When a monorepo has a pnpm-workspace.yaml, use the catalog feature so every workspace package references the same version of a shared dep:

# pnpm-workspace.yaml
packages:
  - "sites/*"
  - "packages/*"
catalog:
  astro: ^6.0.0
  "@astrojs/tailwind": ^6.0.0
  firebase: ^11.0.0

// sites/oriz-blog/package.json
{
  "dependencies": {
    "astro": "catalog:",
    "firebase": "catalog:"
  }
}

Single source of truth for the version. Bump it once in the catalog, every site picks it up on the next install.

Exceptions

A dep may be pinned to a specific version when (and only when):

  1. Astro 6 has known peer-dependency ranges for adapters and integrations — pin those explicitly when the latest minor breaks compatibility.
  2. Firebase major versions occasionally break the JS SDK API in ways the family hasn't migrated to yet — pin the working major until migration is scheduled.
  3. A documented incompatibility (link the issue in the package.json adjacent to the pin, or in a decisions/ file).

Every pin is a temporary measure with a planned exit. No pin is allowed without a comment explaining why and when it goes away.

Why this is a family rule

Staying current is cheap when you do it weekly. It is brutal when you do it yearly. Pick weekly.

Cross-refs