docs/DEPENDENCY_CONSOLIDATION_PLAN.md

Dependency Consolidation Plan

Date: 2025-01-27 Based On: Dependency Analysis Report (reports/dependency-analysis.md) Status: Implementation Plan

---

Executive Summary

This plan consolidates dependencies across 111+ package.json files, identifying opportunities to reduce duplication, standardize versions, and extract shared packages.

Key Findings:

• 86 projects use TypeScript
• 22 projects use ethers (blockchain)
• 20 projects use dotenv
• 18 projects use axios
• 17 projects use zod and react
• 40 projects use ESLint

---

Phase 1: Immediate Actions (Week 1-2)

1.1 Hoist Common DevDependencies to Workspace Root

Target Dependencies:

• typescript (86 projects) → Workspace root
• @types/node (75 projects) → Workspace root
• eslint (40 projects) → Workspace root
• prettier (18 projects) → Workspace root
• @typescript-eslint/parser (15 projects) → Workspace root
• @typescript-eslint/eslint-plugin (15 projects) → Workspace root

Action:

// package.json (root)
{
  "devDependencies": {
    "typescript": "^5.5.4",
    "@types/node": "^20.11.0",
    "eslint": "^9.17.0",
    "prettier": "^3.3.3",
    "@typescript-eslint/parser": "^7.18.0",
    "@typescript-eslint/eslint-plugin": "^7.18.0"
  }
}

Benefits:

• Single source of truth for tooling versions
• Reduced disk space (shared node_modules)
• Faster installs
• Consistent tooling across projects

1.2 Version Standardization

Priority Dependencies:

Dependency	Current Versions	Target Version	Projects Affected
typescript	Multiple (5.3.3, 5.5.4, etc.)	5.5.4	86
zod	Multiple (3.22.4, 3.23.8, etc.)	3.23.8	17
eslint	Multiple (8.56.0, 8.57.0, 9.17.0)	9.17.0	40
prettier	Multiple (3.1.1, 3.2.0, 3.3.3)	3.3.3	18
react	Multiple versions	Latest stable	17
react-dom	Multiple versions	Latest stable	16

Action Plan:

1. Create version mapping document
2. Update package.json files in batches
3. Test after each batch
4. Document breaking changes

---

Phase 2: Shared Package Extraction (Weeks 3-8)

2.1 High-Priority Shared Packages

@workspace/shared-types

Usage: Used across dbis_core, the_order, Sankofa, and others Contents:

• Common TypeScript types
• API response types
• Database model types
• Configuration types

Dependencies to Extract:

• Type definitions only (no runtime deps)

@workspace/shared-utils

Usage: Used in 20+ projects Contents:

• Date formatting utilities
• Validation helpers
• String manipulation
• Common algorithms

Dependencies to Extract:

• date-fns (5+ projects)
• uuid (8 projects)
• Common utility functions

@workspace/shared-config

Usage: All projects with configuration Contents:

• Environment variable schemas
• Configuration validation
• Default configurations

Dependencies to Extract:

• dotenv (20 projects)
• zod (17 projects) - for config validation

@workspace/shared-constants

Usage: DBIS projects, DeFi projects Contents:

• Shared constants
• Enums
• Error codes
• Status values

Dependencies to Extract:

• Constants only (no deps)

2.2 Medium-Priority Shared Packages

@workspace/api-client

Usage: Frontend projects, API consumers Contents:

• HTTP client utilities
• Request/response interceptors
• Error handling
• Retry logic

Dependencies to Extract:

• axios (18 projects)
• Common API patterns

@workspace/validation

Usage: Multiple backend services Contents:

• Zod schemas
• Validators
• Validation utilities

Dependencies to Extract:

• zod (17 projects)
• Validation schemas

@workspace/blockchain

Usage: Blockchain projects Contents:

• Ethereum utilities
• Contract interaction helpers
• Transaction utilities

Dependencies to Extract:

• ethers (22 projects)
• Common blockchain patterns

---

Phase 3: Dependency Registry Setup (Weeks 5-6)

3.1 Private npm Registry

Options:

1. Verdaccio (Recommended - Self-hosted, lightweight)
2. npm Enterprise (Commercial)
3. GitHub Packages (Integrated with GitHub)

Recommendation: Verdaccio for self-hosted, GitHub Packages for cloud

Setup Steps:

1. Deploy Verdaccio instance
2. Configure authentication
3. Set up publishing workflow
4. Configure projects to use registry

3.2 Version Pinning Strategy

Strategy: Semantic versioning with workspace protocol

{
  "dependencies": {
    "@workspace/shared-types": "workspace:*",
    "@workspace/shared-utils": "workspace:^1.0.0"
  }
}

Benefits:

• Always use latest workspace version during development
• Pin versions for releases
• Easy updates across projects

---

Phase 4: Automated Dependency Management (Weeks 7-8)

4.1 Dependabot Configuration

Setup:

• Enable Dependabot for all projects
• Configure update frequency
• Set up security alerts
• Configure auto-merge for patch updates

4.2 Dependency Update Workflow

Process:

1. Weekly dependency scans
2. Automated PR creation
3. Automated testing
4. Manual review for major updates
5. Automated merge for patch/minor (after tests pass)

---

Implementation Checklist

Phase 1: Immediate (Week 1-2)

• Hoist TypeScript to workspace root
• Hoist ESLint to workspace root
• Hoist Prettier to workspace root
• Standardize TypeScript version (5.5.4)
• Standardize ESLint version (9.17.0)
• Standardize Prettier version (3.3.3)
• Update 10 projects as pilot
• Test and verify

Phase 2: Shared Packages (Weeks 3-8)

• Create workspace-shared/ directory
• Set up pnpm workspaces
• Create @workspace/shared-types package
• Create @workspace/shared-utils package
• Create @workspace/shared-config package
• Create @workspace/shared-constants package
• Extract common code to packages
• Update projects to use shared packages
• Test integration

Phase 3: Registry (Weeks 5-6)

• Deploy Verdaccio or configure GitHub Packages
• Set up authentication
• Configure publishing workflow
• Publish first shared packages
• Update projects to use registry

Phase 4: Automation (Weeks 7-8)

• Configure Dependabot
• Set up dependency update workflow
• Configure automated testing
• Set up security scanning
• Document update process

---

Expected Benefits

Immediate (Phase 1)

• 30% reduction in duplicate dev dependencies
• Faster installs (shared node_modules)
• Consistent tooling across projects

Short-Term (Phase 2)

• 50% reduction in duplicate production dependencies
• Easier maintenance (update once, use everywhere)
• Better code reuse

Long-Term (Phase 3-4)

• Automated updates reduce maintenance burden
• Security through automated scanning
• Consistency across all projects

---

Risk Mitigation

Breaking Changes

• Mitigation: Gradual migration, comprehensive testing
• Rollback: Keep old dependencies until migration complete

Version Conflicts

• Mitigation: Use workspace protocol, pin versions for releases
• Testing: Test all projects after updates

Registry Availability

• Mitigation: Use GitHub Packages as backup
• Monitoring: Monitor registry health

---

Success Metrics

• 30% reduction in duplicate dependencies (Phase 1)
• 50% reduction in duplicate dependencies (Phase 2)
• 10+ shared packages created (Phase 2)
• 80% of projects using shared packages (Phase 2)
• Automated dependency updates working (Phase 4)
• Zero security vulnerabilities in dependencies (Phase 4)

---

Last Updated: 2025-01-27 Next Review: After Phase 1 completion