Package Management

This project uses PNPM inside DDEV to ensure consistent, reproducible dependency management across all environments. All package operations must be executed through:

ddev pnpm <command>

Running commands through DDEV ensures:

• consistent Node & PNPM versions
• deterministic installs
• a stable lockfile
• reproducible builds for all contributors

---

Installing New Packages

To add a new dependency:

ddev pnpm add <package>

This will install the package and pin the version.

Always pin versions

Avoid installing packages without specifying a version:

# Avoid
ddev pnpm add some-package@latest

This will install floating versions, which makes builds unpredictable.

Always install explicit stable versions:

# Recommended
ddev pnpm add some-package
ddev pnpm add some-package@1.4.2

Rules for installing packages

• Only install actively maintained packages.
• Check if a package is healthy: commits, issues, downloads, security warnings.
• Prefer built-in Next.js/React/TypeScript features where possible.
• Avoid “just because it’s nice” dependencies — each dependency has long-term cost.

Caution

Some projects might not have automatic pinning enable so please check if the package is actually pinned before committing your changes.

---

Updating Packages

Update a single package

ddev pnpm add <package>@<new-version>

Example:

ddev pnpm add zod@3.23.8

Update all packages (use sparingly)

ddev pnpm update

Before merging such updates, always:

• review the diff
• check changelogs
• validate major version bumps
• run the project + tests

---

Removing Packages

Remove a dependency cleanly:

ddev pnpm remove <package-name>

PNPM will automatically update both package.json and pnpm-lock.yaml.

---

Version Locking & Lockfile Hygiene

• Commit pnpm-lock.yaml at all times.
• Do not edit the lockfile manually.
• Always run package commands using ddev pnpm to avoid environment drift.
• After pulling new changes or switching branches, run:

ddev pnpm install

This ensures node_modules matches the lockfile exactly.

---

Anti-Patterns to Avoid

• Installing latest, alpha, beta, or rc versions unless explicitly required
• Adding random packages from blog posts or Stack Overflow
• Installing packages you don’t fully understand
• Adding dependencies just for convenience

Every dependency impacts:

• build size
• attack surface
• maintainability
• future upgrade cost

---

Command Summary

Task	Command	Notes
Install a package	ddev pnpm add pkg@x.y.z	Always pin versions
Update a package	ddev pnpm add pkg@new-version	Review changelogs
Update all packages	ddev pnpm update	Use sparingly
Remove a package	ddev pnpm remove pkg	Safe cleanup
Sync dependencies	ddev pnpm install	After lockfile changes