Dependency Management

Package Installation

Adding Dependencies

Production dependency

npm install package-name

Development dependency

npm install -D package-name

Specific version

npm install package-name@1.2.3

Latest version

npm install package-name@latest

When to Use devDependencies

{ "dependencies": { // Runtime code - ships to production "react": "^19.1.0", "drizzle-orm": "^0.44.3", "stripe": "^18.3.0" }, "devDependencies": { // Build/test tools - not in production bundle "@playwright/test": "^1.54.2", "typescript": "^5.8.3", "vitest": "^3.2.4", "@types/react": "^19.1.8" } }

Version Ranges

Semver Notation

{ "dependencies": { // Exact version - use sparingly "critical-lib": "1.2.3",

// Patch updates only (1.2.x)
"stable-lib": "~1.2.3",

// Minor updates (1.x.x) - recommended for most
"flexible-lib": "^1.2.3",

// Any version - avoid in production
"any-lib": "*"

} }

Recommended Approach

Use ^ (caret) for most dependencies to get bug fixes and minor improvements:

{ "react": "^19.1.0", // Will update to 19.x.x "typescript": "^5.8.3" // Will update to 5.x.x }

Updating Dependencies

Check for Updates

Check outdated packages

npm outdated

Interactive update tool

npx npm-check-updates -i

Safe Update Process

Review changelogs for breaking changes
Update in stages - don't update everything at once
Run tests after each update
Commit separately for easy rollback

Update single package

npm update package-name

Update all (respecting semver ranges)

npm update

Update to latest (may include breaking changes)

npm install package-name@latest

Lock File Management

package-lock.json

Always commit the lock file
Don't manually edit - let npm manage it
Use npm ci in CI/CD for reproducible builds

Clean install from lock file (CI/CD)

npm ci

Install and update lock file (development)

npm install

Security Updates

Audit Dependencies

Check for vulnerabilities

npm audit

Fix automatically where possible

npm audit fix

Force fix (may include breaking changes)

npm audit fix --force

Regular Maintenance

Run npm audit weekly
Update security patches immediately
Review and update major versions monthly

Common Dependencies in This Project

Core Framework

{ "@tanstack/react-start": "^1.143.3", "@tanstack/react-router": "^1.143.3", "@tanstack/react-query": "^5.83.0", "react": "^19.1.0", "react-dom": "^19.1.0" }

Database

{ "drizzle-orm": "^0.44.3", "pg": "^8.16.3", "drizzle-kit": "^0.31.4" // devDependency }

UI Components

{ "@radix-ui/react-dialog": "^1.1.14", "@radix-ui/react-dropdown-menu": "^2.1.15", "tailwindcss": "^4.1.11", "lucide-react": "^0.528.0", "class-variance-authority": "^0.7.1" }

Forms & Validation

{ "react-hook-form": "^7.62.0", "@hookform/resolvers": "^5.2.1", "zod": "^4.0.10" }

Payments & Auth

{ "stripe": "^18.3.0", "@stripe/stripe-js": "^7.6.1", "arctic": "^3.7.0" }

Testing

{ "@playwright/test": "^1.54.2", "vitest": "^3.2.4", "@vitest/coverage-v8": "^3.2.4" }

Peer Dependencies

Some packages require specific peer dependencies:

Check peer dependency warnings

npm install

Install missing peer dependencies

npm install react@19 react-dom@19

Radix UI Peer Dependencies

Radix components require React as a peer:

{ "peerDependencies": { "react": "^16.8 || ^17 || ^18 || ^19", "react-dom": "^16.8 || ^17 || ^18 || ^19" } }

Troubleshooting

Dependency Conflicts

Clear cache and reinstall

rm -rf node_modules package-lock.json npm install

Force resolution

npm install --force

Check why a package is installed

npm explain package-name

Version Mismatches

List all installed versions

npm ls package-name

Deduplicate

npm dedupe

Import Optimization

Tree-Shaking Friendly Imports

// GOOD: Import specific items (tree-shakeable) import { Button } from "~/components/ui/button"; import { eq, and } from "drizzle-orm";

// AVOID: Barrel imports of large libraries // import * as RadixUI from "@radix-ui/react-primitives";

Dynamic Imports for Large Libraries

// Lazy load heavy dependencies const marked = await import("marked"); const { OpenAI } = await import("openai");

Dependency Checklist

Lock file is committed to git
npm audit shows no high/critical vulnerabilities
DevDependencies are correctly categorized
No * version ranges in production
Peer dependencies are satisfied
Tree-shaking friendly imports used
Large libraries lazy-loaded where possible
Regular updates scheduled (monthly)
Breaking changes reviewed before major updates
CI uses npm ci for reproducible builds

agentic-jumpstart-dependency-management

Safety Notice

Copy this and send it to your AI assistant to learn