# ADR-002: pnpm Per-App Dependencies

## Status
Accepted

## Context
CMS-aiChemist uses a monorepo structure with multiple applications and shared packages:

- **apps/web/** - Next.js 15 application
- **apps/cms-theme/** - Astro 6 + EmDash application
- **packages/ui/** - Shared React component primitives
- **packages/tokens/** - Design tokens from Penpot
- **packages/schemas/** - Shared content and validation schemas
- **packages/agents/** - ADW prompts and policies

We need a dependency management strategy that balances:
- Consistency across apps (shared UI and tokens should use same versions)
- Build isolation (each app can build and deploy independently)
- CI/CD simplicity (avoid workspace hoisting complexity)
- Developer ergonomics (predictable resolution, clear dependency graphs)

## Decision
Use pnpm with per-app lockfiles rather than a single workspace root. Each app (web, cms-theme) and package (ui, tokens, schemas, agents) maintains its own pnpm-lock.yaml.

Shared packages are referenced via relative paths in package.json:
```json
"dependencies": {
  "@cms/ui": "workspace:*",
  "@cms/tokens": "workspace:*"
}
```

There is no root workspace configuration. Each directory is independently installable and buildable.

## Consequences

### Positive
- **Simpler CI**: Each app builds independently without workspace context
- **Isolation**: Dependency conflicts in one app don't affect others
- **Explicit**: No hoisting surprises - dependencies are where package.json says they are
- **Portable**: Apps can be moved or extracted without workspace restructuring
- **Clear paths**: Packages referenced via relative paths, no magic resolution

### Negative
- **Manual sync**: Must update dependencies in multiple package.json files
- **Duplicate installs**: Same dependency may be installed multiple times
- **No shared scripts**: Can't run "install all" or "build all" from root
- **Inconsistency risk**: Apps may drift to different versions of shared deps

### Neutral
- Apps use different Node.js versions (web: default, cms-theme: 22+ via fnm)
- No root package.json - project root is not a Node.js package
- Build process: cd to app directory → pnpm install → pnpm build
- Production deployment requires building both apps separately

### Mitigation Strategies
- Document expected dependency versions in CLAUDE.md
- Use dependabot or renovate to keep versions aligned
- CI checks can validate shared package versions match across apps
- Consider scripts in ops/ for batch operations if needed