agentic-jumpstart-dependency-management

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"

}

}

```

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

}

```

Check for Updates

```bash

# 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

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

```

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

```

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

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"

}

```

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"

}

}

```

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

```

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");

```

• [ ] 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