Dependency Management & Technology Selection
Build vs Buy Decision Tree
┌─ Is this core business logic?
│ ├─ Yes → Build (keep control)
│ └─ No → ↓
│
├─ Is there a mature, well-maintained library?
│ ├─ Yes → Use library
│ └─ No → ↓
│
├─ Would building it take > 2 days?
│ ├─ Yes → Find alternative or build
│ └─ No → Build (simpler than integrating)
Golden Rule: Only build when you need competitive advantage. Everything else, use proven solutions.
Library Evaluation Criteria
Before adding ANY dependency, verify:
Maintenance Health
- ✅ Last commit within 6 months
- ✅ Issues are being addressed
- ✅ No major open bugs related to your use case
Ecosystem Health
- ✅ GitHub stars > 100 (for general libs)
- ✅ Weekly downloads > 10k (for npm)
- ✅ No known security vulnerabilities (run
npm audit or snyk)
Bundle Size
- ⚠️ Is this library adding > 50KB minified?
- ⚠️ Does it have tree-shaking support?
- ⚠️ Can you use a smaller alternative?
API Stability
- ✅ Has stable v1.0+ release
- ❌ Avoid libraries with 0.x.x versions (unstable)
Dependency Categories
| Type |
Strategy |
| Utility libraries (lodash, date-fns) |
Use, but prefer modern alternatives (native APIs, smaller libs) |
| UI frameworks/components (React, shadcn/ui) |
Standardize, don't mix |
| Backend SDKs (Stripe, AWS SDK) |
Use official SDKs, never unofficial |
| Dev dependencies |
Minimize, remove unused |
| Polyfills |
Avoid, target modern browsers |
Version Management
Use semantic versioning strictly
^1.2.3 → Accept 1.x.x updates (patch + minor)~1.2.3 → Accept 1.2.x updates (patch only)1.2.3 → Exact version (for critical deps)
Lock files are sacred
- Commit
package-lock.json, yarn.lock, poetry.lock
- Never manually edit lock files
- Same lock file across all environments
Update strategy
# Monthly: Check for security updates
npm audit
# Quarterly: Minor version updates
npm update
# Yearly: Major version updates (requires testing)
# Example: Upgrade React 18 → 19
When to Avoid Dependencies
❌ Don't add if:
- It's 5 lines of code you can write yourself
- You only use 10% of a large library
- There's no clear migration path if it's abandoned
- It adds unnecessary complexity
✅ Do add if:
- It's a well-solved problem (date parsing, validation)
- It's security-sensitive (crypto, auth)
- It has active community and documentation
Security Checklist
Before merging any PR with new dependencies:
Package.json Best Practices
{
"dependencies": {
"react": "^19.0.0", // Standard deps
"@stripe/stripe-js": "^3.0.0" // Scoped packages for official SDKs
},
"devDependencies": {
"typescript": "^5.0.0", // Dev tools
"prettier": "^3.0.0"
},
"overrides": {
"minimist": "^1.2.8" // Force security patch
},
"engines": {
"node": ">=18.0.0" // Minimum version
}
}
Removal Strategy
Quarterly dependency audit:
- List all dependencies:
npm list --depth=0
- Identify unused:
npx depcheck
- Check each against actual usage in codebase
- Remove unused:
npm uninstall <package>
- Test thoroughly after removal
1---2name: dependency-23description: Dependency management and technology selection. Apply when introducing new libraries, choosing technologies, or managing package versions.4---5
6# Dependency Management & Technology Selection
7
8## Build vs Buy Decision Tree
9
10```
11┌─ Is this core business logic?
12│ ├─ Yes → Build (keep control)
13│ └─ No → ↓
14│
15├─ Is there a mature, well-maintained library?
16│ ├─ Yes → Use library
17│ └─ No → ↓
18│
19├─ Would building it take > 2 days?
20│ ├─ Yes → Find alternative or build
21│ └─ No → Build (simpler than integrating)
22```
23
24**Golden Rule**: Only build when you need competitive advantage. Everything else, use proven solutions.
25
26## Library Evaluation Criteria
27
28Before adding ANY dependency, verify:
29
301. **Maintenance Health**
31 - ✅ Last commit within 6 months
32 - ✅ Issues are being addressed
33 - ✅ No major open bugs related to your use case
34
352. **Ecosystem Health**
36 - ✅ GitHub stars > 100 (for general libs)
37 - ✅ Weekly downloads > 10k (for npm)
38 - ✅ No known security vulnerabilities (run `npm audit` or `snyk`)
39
403. **Bundle Size**
41 - ⚠️ Is this library adding > 50KB minified?
42 - ⚠️ Does it have tree-shaking support?
43 - ⚠️ Can you use a smaller alternative?
44
454. **API Stability**
46 - ✅ Has stable v1.0+ release
47 - ❌ Avoid libraries with 0.x.x versions (unstable)
48
49## Dependency Categories
50
51| Type | Strategy |
52|------|----------|
53| **Utility libraries** (lodash, date-fns) | Use, but prefer modern alternatives (native APIs, smaller libs) |
54| **UI frameworks/components** (React, shadcn/ui) | Standardize, don't mix |
55| **Backend SDKs** (Stripe, AWS SDK) | Use official SDKs, never unofficial |
56| **Dev dependencies** | Minimize, remove unused |
57| **Polyfills** | Avoid, target modern browsers |
58
59## Version Management
60
611. **Use semantic versioning strictly**
62 - `^1.2.3` → Accept 1.x.x updates (patch + minor)
63 - `~1.2.3` → Accept 1.2.x updates (patch only)
64 - `1.2.3` → Exact version (for critical deps)
65
662. **Lock files are sacred**
67 - Commit `package-lock.json`, `yarn.lock`, `poetry.lock`
68 - Never manually edit lock files
69 - Same lock file across all environments
70
713. **Update strategy**
72 ```bash
73 # Monthly: Check for security updates
74 npm audit
75
76 # Quarterly: Minor version updates
77 npm update
78
79 # Yearly: Major version updates (requires testing)
80 # Example: Upgrade React 18 → 19
81 ```
82
83## When to Avoid Dependencies
84
85❌ **Don't add if**:
86- It's 5 lines of code you can write yourself
87- You only use 10% of a large library
88- There's no clear migration path if it's abandoned
89- It adds unnecessary complexity
90
91✅ **Do add if**:
92- It's a well-solved problem (date parsing, validation)
93- It's security-sensitive (crypto, auth)
94- It has active community and documentation
95
96## Security Checklist
97
98Before merging any PR with new dependencies:
99
100- [ ] Run security audit: `npm audit` / `pip-audit`
101- [ ] Check for known CVEs in the package
102- [ ] Verify maintainer identity (avoid typosquatting)
103- [ ] Review license compatibility (MIT, Apache 2.0, BSD preferred)
104- [ ] Check if package has been compromised (replaced)
105
106## Package.json Best Practices
107
108```json
109{
110 "dependencies": {
111 "react": "^19.0.0", // Standard deps
112 "@stripe/stripe-js": "^3.0.0" // Scoped packages for official SDKs
113 },
114 "devDependencies": {
115 "typescript": "^5.0.0", // Dev tools
116 "prettier": "^3.0.0"
117 },
118 "overrides": {
119 "minimist": "^1.2.8" // Force security patch
120 },
121 "engines": {
122 "node": ">=18.0.0" // Minimum version
123 }
124}
125```
126
127## Removal Strategy
128
129Quarterly dependency audit:
1301. List all dependencies: `npm list --depth=0`
1312. Identify unused: `npx depcheck`
1323. Check each against actual usage in codebase
1334. Remove unused: `npm uninstall <package>`
1345. Test thoroughly after removal
majiayu000