dev-dependency-management

What this skill does

# Dependency Management — Production Patterns

**Modern Best Practices (January 2026)**: Lockfile-first workflows, automated security scanning (Dependabot, Snyk, Socket.dev), semantic versioning, minimal dependencies principle, monorepo workspaces (pnpm, Nx, Turborepo), supply chain security (SBOM, AI BOM, Sigstore), reproducible builds, and AI-generated code validation.

---

## When to Use This Skill

The agent should invoke this skill when a user requests:

- Adding new dependencies to a project
- Updating existing dependencies safely
- Resolving dependency conflicts or version mismatches
- Auditing dependencies for security vulnerabilities
- Understanding lockfile management and reproducible builds
- Setting up monorepo workspaces (pnpm, npm, yarn)
- Managing transitive dependencies and overrides
- Choosing between similar packages (bundle size, maintenance, security)
- Dependency version constraints and semantic versioning
- Dependency security best practices and supply chain security
- Troubleshooting "dependency hell" scenarios
- Package manager configuration and optimization
- Creating reproducible builds across environments

---

## Quick Reference

| Task | Tool/Command | Key Action | When to Use |
|------|--------------|------------|-------------|
| **Install from lockfile** | `npm ci`, `poetry install`, `cargo build` | Clean install, reproducible | CI/CD, production deployments |
| **Add dependency** | `npm install <pkg>`, `poetry add <pkg>` | Updates lockfile automatically | New feature needs library |
| **Update dependencies** | `npm update`, `poetry update`, `cargo update` | Updates within version constraints | Monthly/quarterly maintenance |
| **Check for vulnerabilities** | `npm audit`, `pip-audit`, `cargo audit` | Scans for known CVEs | Before releases, weekly |
| **View dependency tree** | `npm ls`, `pnpm why`, `pipdeptree` | Shows transitive dependencies | Debugging conflicts |
| **Override transitive dep** | `overrides` (npm), `pnpm.overrides` | Force specific version | Security patch, conflict resolution |
| **Monorepo setup** | `pnpm workspaces`, `npm workspaces` | Shared dependencies, cross-linking | Multi-package projects |
| **Check outdated** | `npm outdated`, `poetry show --outdated` | Lists available updates | Planning update sprints |

---

## Decision Tree: Dependency Management

```text
User needs: [Dependency Task]
    ├─ Adding new dependency?
    │   ├─ Check: Do I really need this? (Can implement in <100 LOC?)
    │   ├─ Check: Is it well-maintained? (Last commit <6 months, >10k downloads/week)
    │   ├─ Check: Bundle size impact? (Use Bundlephobia for JS)
    │   ├─ Check: Security risks? (`npm audit`, Snyk)
    │   └─ If all checks pass → Add with `npm install <pkg>` → Commit lockfile
    │
    ├─ Updating dependencies?
    │   ├─ Security vulnerability? → `npm audit fix` → Test → Deploy immediately
    │   ├─ Routine update?
    │       ├─ Patch versions → `npm update` → Safe, do frequently
    │       ├─ Minor/major → Check CHANGELOG → Test in staging → Update gradually
    │       └─ All at once → [FAIL] RISKY → Update in batches instead
    │
    ├─ Dependency conflict?
    │   ├─ Transitive dependency issue?
    │       ├─ View tree: `npm ls <package>`
    │       ├─ Use overrides sparingly: `overrides` in package.json
    │       └─ Document why override is needed
    │   └─ Peer dependency mismatch?
    │       └─ Check version compatibility → Update parent or child
    │
	├─ Monorepo project?
	│   ├─ Use pnpm workspaces (recommended default)
	│   ├─ Shared deps → Root package.json
	│   ├─ Package-specific → Package directories
	│   └─ Use Nx or Turborepo for task caching
	│
	└─ Choosing package manager?
	    ├─ New JS project → **pnpm** (recommended default) or **Bun** (often faster; verify ecosystem maturity)
	    ├─ Enterprise monorepo → **pnpm** (mature workspace support)
	    ├─ Speed-focused experimentation → **Bun** (verify ecosystem maturity)
	    ├─ Existing npm project → Migrate to pnpm or stay (check team preference)
	    ├─ Python → **uv** (fast), Poetry (mature), pip+venv (simple)
	    └─ Data science → **conda** or **uv** (faster environment setup)
```

---

## Navigation: Core Patterns

### Lockfile Management

**[`references/lockfile-management.md`](references/lockfile-management.md)**

Lockfiles ensure reproducible builds by recording exact versions of all dependencies (direct + transitive). Essential for preventing "works on my machine" issues.

- Golden rules (always commit, never edit manually, regenerate on changes)
- Commands by ecosystem (npm ci, poetry install, cargo build)
- Troubleshooting lockfile conflicts
- CI/CD integration patterns

### Semantic Versioning (SemVer)

**[`references/semver-guide.md`](references/semver-guide.md)**

Understanding version constraints (`^`, `~`, exact) and how to specify dependency ranges safely.

- SemVer format (MAJOR.MINOR.PATCH)
- Version constraint syntax (caret, tilde, exact)
- Recommended strategies by project type
- Cross-ecosystem version management

### Dependency Security Auditing

**[`references/security-scanning.md`](references/security-scanning.md)**

Automated security scanning, vulnerability management, and supply chain security best practices.

- Automated tools (Dependabot, Snyk, GitHub Advanced Security)
- Running audits (npm audit, pip-audit, cargo audit)
- CI integration and alert configuration
- Incident response workflows

### Dependency Selection

**[`references/dependency-selection-guide.md`](references/dependency-selection-guide.md)**

Deciding whether to add a new dependency and choosing between similar packages.

- Minimal dependencies principle (best dependency is the one you don't add)
- Evaluation checklist (maintenance, bundle size, security, alternatives)
- Choosing between similar packages (comparison matrix)
- When to reject a dependency

### Update Strategies

**[`references/update-strategies.md`](references/update-strategies.md)**

Keeping dependencies up to date safely while minimizing breaking changes and security risks.

- Update strategies (continuous, scheduled, security-only)
- Safe update workflow (check outdated, categorize risk, test, deploy)
- Automated update tools (Dependabot, Renovate, npm-check-updates)
- Handling breaking changes and rollback plans

### Monorepo Management

**[`references/monorepo-patterns.md`](references/monorepo-patterns.md)**

Managing multiple related packages in a single repository with shared dependencies.

- Workspace tools (pnpm, npm, yarn workspaces)
- Monorepo structure and organization
- Build optimization (Nx, Turborepo)
- Versioning and publishing strategies

### Transitive Dependencies

**[`references/transitive-dependencies.md`](references/transitive-dependencies.md)**

Dealing with dependencies of your dependencies (indirect dependencies).

- Viewing dependency trees (npm ls, pnpm why, pipdeptree)
- Resolving transitive conflicts (overrides, resolutions, constraints)
- Security risks and version conflicts
- Best practices (use sparingly, document, test)

### Ecosystem-Specific Guides

**[`references/ecosystem-guides.md`](references/ecosystem-guides.md)**

Language and package-manager-specific best practices.

- Node.js (npm, yarn, pnpm comparison and best practices)
- Python (pip, poetry, conda)
- Rust (cargo), Go (go mod), Java (maven, gradle)
- PHP (composer), .NET (nuget)

### Anti-Patterns

**[`references/anti-patterns.md`](references/anti-patterns.md)**

Common mistakes to avoid when managing dependencies.

- Critical anti-patterns (not committing lockfiles, wildcards, ignoring audits)
- Dangerous anti-patterns (never updating, deprecated packages)
- Moderate anti-patterns (overusing overrides, ignoring peer deps)

### Container Dependency Patterns

**[`references/container-dependency-patterns.md`](references/container-dependency-patterns.md)**

Managing dependencies in containerized environments (Docker, OCI).

- Multi-stage builds, layer caching, base im