Update Packages

First Step: Create Branch (MANDATORY)

Before touching any packages, create a dedicated branch:

but branch new chore/update-packages-$(date +%y%m%d-%H%M)

Rules:

• Never reuse an existing update-packages branch
• Always create a fresh branch with the current timestamp
• All package update commits go to this branch

Definition of Done

• bun upgrade shows all packages at latest versions
• No packages remain to select or update
• All checks pass (bun run check)
• All relevant tests pass

If Bun Updates

When the Bun runtime itself has a new version:

1. Update packageManager field in root package.json:

   "packageManager": "bun@X.Y.Z"
   

2. Update all Dockerfiles that reference BUN_VERSION:

   ARG BUN_VERSION=X.Y.Z
   

3. Update CI pipeline BUN_VERSION environment variable in all relevant pipeline files.

4. Run checks to confirm nothing broke:

   bun run check
   

5. Commit message format:

   chore: update bun to vX.Y.Z
   

If Playwright Updates

When @playwright/test or playwright npm version changes:

1. The Docker image version must match the npm package version exactly.

2. Find all references to the Playwright Docker image across:

   • Dockerfile files
   • CI/CD pipeline YAML files
   • Kubernetes Helm values files
   • Any other infrastructure files

3. Update all references to use the matching image tag:

   mcr.microsoft.com/playwright:vX.Y.Z-noble
   

4. Run E2E tests to confirm compatibility:

   bun run test:e2e
   

5. Commit message format:

   chore: update playwright to vX.Y.Z
   

Catalog Packages

Some packages are managed via Bun's catalog and require manual version checking:

# Check latest version of a catalog package
npm view <package-name> version

# Check all versions available
npm view <package-name> versions --json

Update catalog entries in package.json or bun.lockb manually after confirming the latest version.

Package Groups (Update Together)

These packages must always be updated as a group — mismatched versions cause type errors or runtime failures:

Group	Packages
tanstack-router	@tanstack/react-router, @tanstack/router-devtools, @tanstack/router-plugin, @tanstack/start
tanstack-query	@tanstack/react-query, @tanstack/react-query-devtools, @tanstack/query-core
trpc	@trpc/server, @trpc/client, @trpc/react-query, @trpc/tanstack-react-query
effect	effect, @effect/schema, @effect/platform, @effect/language-service
drizzle	drizzle-orm, drizzle-kit, drizzle-zod
pino	pino, pino-pretty, @types/pino
playwright	@playwright/test, playwright (+ Docker image sync — see above)

Update Strategy

For regular packages:

1. Run bun upgrade to update all packages interactively
2. Select packages to update (prefer updating all unless a known breaking change exists)
3. Run bun run check after each group update
4. Fix any breaking changes before proceeding to the next group

For catalog packages:

1. Manually check latest version with npm view <package> version
2. Update the version in the catalog configuration
3. Run bun install to apply
4. Run bun run check

Testing Requirements

Update Type	Required Tests
UI/component packages (@base-ui/react, etc.)	bun run check + visual review in browser
TRPC / TanStack Router	bun run check + bun run test
Drizzle ORM	bun run check + bun run test
Effect packages	bun run check + bun run test
Playwright	bun run check + bun run test:e2e
Bun runtime	bun run check + bun run test + bun run test:e2e
All others	bun run check

Cache Recovery (Bun)

If packages fail to install or you see stale cache errors after updating:

bun clean:packages && bun install

This clears the local package cache and performs a fresh install.

Common Breaking Changes

Package	Common Issue	Fix
@effect/language-service	Version must match effect core exactly	Always update together with effect
@types/react	React 19 types changed significantly; some third-party types conflict	Check peer deps, may need --legacy-peer-deps workaround or type overrides
@base-ui/react	API surface changes frequently in pre-stable releases	Review changelog, update component usage accordingly

Guardrails

• DO NOT update packages with workspace:* version specifiers — these are internal monorepo packages managed separately
• DO NOT skip @typescript/native-preview updates — this package affects TypeScript LSP performance and should stay current
• DO NOT use bun outdated to check for updates — it misses packages that are in the catalog or have non-standard version specifiers; use bun upgrade interactively instead