SKILL.md

--- frontmatter

name: agentic-jumpstart-dependency-management
description: Dependency management best practices for npm projects with 40+ dependencies. Use when adding packages, updating dependencies, resolving conflicts, or when the user mentions npm, packages, dependencies, versions, or updates.

Dependency Management

Package Installation

Adding Dependencies

bash

# 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

json

{
  "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

json

{
  "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:

json

{
  "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

bash

# 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

bash

# 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

bash

# Clean install from lock file (CI/CD)
npm ci

# Install and update lock file (development)
npm install

Security Updates

Audit Dependencies

bash

# 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

json

{
  "@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

json

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

UI Components

json

{
  "@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

json

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

Payments & Auth

json

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

Testing

json

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

Peer Dependencies

Some packages require specific peer dependencies:

bash

# 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:

json

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

Troubleshooting

Dependency Conflicts

bash

# 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

bash

# List all installed versions
npm ls package-name

# Deduplicate
npm dedupe

Import Optimization

Tree-Shaking Friendly Imports

typescript

// 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

typescript

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

Dependency Management

Package Installation

Adding Dependencies

When to Use devDependencies

Version Ranges

Semver Notation

Recommended Approach

Updating Dependencies

Check for Updates

Safe Update Process

Lock File Management

package-lock.json

Security Updates

Audit Dependencies

Regular Maintenance

Common Dependencies in This Project

Core Framework

Database

UI Components

Forms & Validation

Payments & Auth

Testing

Peer Dependencies

Radix UI Peer Dependencies

Troubleshooting

Dependency Conflicts

Version Mismatches

Import Optimization

Tree-Shaking Friendly Imports

Dynamic Imports for Large Libraries

Dependency Checklist