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

1. Review changelogs for breaking changes
2. Update in stages - don't update everything at once
3. Run tests after each update
4. 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