Dependency Migration
Replace one library with another, or migrate deprecated API patterns within the same library.
Quick Start
Replace moment.js with date-fns
Migrate from webpack to vite
Remove deprecated forwardRef usage (React 19)
Switch from lodash to es-toolkit
Migrate Vue Options API to Composition API
Scope
| Type |
Example |
Trigger |
| Library replacement |
moment.js → date-fns |
"replace X with Y" |
| API pattern migration |
React 19 forwardRef removal |
"remove deprecated X", "migrate to new Y API" |
Both types follow the same test-first workflow below.
Workflow
Non-linear execution: Phases are numbered for reference, not strict order. If findings in any phase invalidate earlier assumptions, restart from the affected phase.
Phase 1: Environment Analysis
- Detect package manager from lockfile (see package-managers.md)
- Detect monorepo structure
- Detect CI, hooks, changeset config (see repo-conventions.md)
- Detect test infrastructure (test runner, tsconfig.json, linter)
Phase 2: Identify Migration Target
For library replacement:
- Parse source library (to remove) and target library (to add)
- Detect current usage scope: grep for imports/requires of source library
- Count affected files and usage patterns
For API pattern migration:
- Identify deprecated/removed API pattern
- Scan all occurrences in codebase
- Identify the replacement pattern from docs
Phase 3: Documentation & Compatibility Analysis
Consult all sources (use subagents for parallel lookup when possible; see context7-integration.md):
- Context7 → Query both libraries for API comparison, migration guides
- Community resources → Search for known migration guides
- Code analysis → Map source API usage to target equivalents
Conflict resolution: If sources disagree on API equivalence or behavior, use the most conservative conclusion and flag the discrepancy.
Build an API mapping table:
| Source |
Target |
Notes |
moment().format('YYYY') |
format(date, 'yyyy') |
Different format tokens |
React.forwardRef((props, ref) => ...) |
function Component({ ref, ...props }) |
ref is now a regular prop |
See migration-patterns.md for methodology and common patterns.
Phase 3.5: Official Tools & Compat Layer Detection
Check for official/community migration tools before writing custom migrations:
For library replacement:
- Compat layer — e.g.,
es-toolkit/compat for lodash
- Ask user: "Use compat for gradual migration, or full replacement?"
- Compat-first: swap import paths → verify → optionally migrate to native API later
- Codemods — e.g.,
jscodeshift transforms from library authors
For API pattern migration:
- Official codemods — e.g.,
npx react-codemod rename-unsafe-lifecycles
- Framework CLI migration — e.g.,
npx @angular/cli update, npx storybook automigrate
Decision flow:
- Codemod exists → run codemod first, handle remaining manually
- Compat layer available → ask user preference (gradual vs full)
- Neither → proceed to Phase 4
Phase 3.7: Related Package Detection
For library replacement:
- Check if
@types/<source> exists → should be removed (scoped: @scope/pkg → @types/scope__pkg)
- Check if target requires
@types/<target> or companion packages
- For each related package found, also check for its
@types/ counterpart (e.g., react-dom → @types/react-dom)
- Check for related plugins/adapters referencing the source library
For API pattern migration:
- Usually no related packages needed, but check for community wrappers
Present findings and ask user whether to include.
Phase 4: Test-First Verification
Validate the migration approach before batch execution.
- Scan all usage — comprehensive grep for all patterns to migrate
- Write test diffs in /tmp — pick representative examples (not all files):
- Select 2-3 diverse usage patterns (simple, complex, edge case). If more than 10 distinct patterns exist, sample at least 30% and reflect actual coverage in the confidence index
- Create migrated versions in /tmp
- Run type check + tests against migrated snippets
/tmp/deps-shift-verify-<package>-<timestamp>/
├── package.json # Minimal deps (target package only)
├── tsconfig.json # Copied from project, paths/aliases adjusted for /tmp
├── original/ # Copy of affected code snippets
├── migrated/ # Proposed migration applied
└── test-runner.sh # Must run tsc --noEmit at minimum, must NOT be just exit 0
Environment setup: Create a minimal package.json, install only the target package version fresh. Copy project's tsconfig.json; remove paths, baseUrl, and references fields that point to project-specific locations — /tmp resolves modules through its own node_modules only. Never mutate the project's actual node_modules.
- Verify approach works before committing to full migration
- Pass → proceed to Phase 5
- Fail → iterate (max 3 attempts), then present failure analysis
Fallback: When tests can't be written → subagent 3-pass review loop:
- Pass 1 (Direct): correctness of API mapping, import resolution
- Pass 2 (Best Practice): idiomatic target library usage
- Pass 3 (Critical Think): edge cases, behavioral differences, risks
- Fix + loop until all passes clean
Phase 5: Migration Plan & Confidence Index
Present structured plan with confidence index:
- File-by-file change summary
- API mapping table (validated by Phase 4)
- Potential issues / no direct equivalent
- Confidence index with factor breakdown and boost options
- Repo convention actions
Always get user confirmation before executing.
Phase 6: Execute Migration
- Install target library (if library replacement)
- Apply transformations file by file using validated mapping
- Checkpoint: Verify all files have been transformed — grep for remaining source library imports. If any remain, do NOT proceed to removal
- Check for peer dependency conflicts — present options if found
- Clean up unused imports/types
- Clean up /tmp verification files
Note: Source library removal happens in Phase 8 after final verification passes. Do NOT remove it here — keeping it installed during verification ensures rollback is possible if issues are found.
Phase 7: Repo Convention Compliance
Detect and follow project conventions (see repo-conventions.md):
- Changesets → create changeset file
- Conventional commits → follow format
- CI checks → run matching local commands
- Pre-commit hooks → ensure hooks pass
- Custom scripts → run test, lint, typecheck
Phase 8: Final Verification
- Type check → 2. Lint → 3. Test suite → 4. Build
- For complex migrations: run subagent Pass 3 (Critical Think) as final quality gate
- After all checks pass: Remove source library from
package.json (if library replacement). If source is a transitive dep of other packages, it stays in lockfile — only remove the direct dependency
- Run install to update lockfile after removal
- All pass → report success
- Failures → analyze if migration-related, attempt fix, present remaining to user (source library is still installed, so rollback is straightforward)
Guidelines
DO
- Build a complete API mapping table — map every source API to target equivalent before migrating
- Check for official codemods first — search npm registry and migration guides before writing custom transforms
- Offer compat layers when available — ask user preference (gradual vs full), never assume
- Test migration approach in /tmp first — validate on representative samples before batch
- Use Context7 for both libraries — query source and target library docs in parallel
- Handle "no equivalent" cases — ask user, implement custom wrapper, or document manual step
- Always confirm before execution — present migration plan, get user approval
- Follow repo conventions — detect and comply with changesets, commit format, CI checks
DON'T
- Skip codemod detection — always check for official tools first
- Skip test-first verification — never execute batch migration without validating approach
- Remove source library prematurely — verify all usage migrated before removing
- Assume API equivalence — subtle behavioral differences exist (async vs sync, shallow vs deep copy)
- Force migration when tests fail — present failure analysis, let user decide
- Assume compat layer preference — always ask user (gradual vs clean break)
- Migrate test files last — migrate tests alongside implementation to catch issues early
Error Handling
| Error |
Action |
| No direct API equivalent found |
Document gap, ask user for custom wrapper or alternative approach |
| Codemod crashes partway |
Report progress, show transformed files, suggest manual completion |
| Context7 MCP tool not found |
Suggest installation, continue with community guides + code analysis |
| Type errors after migration |
Analyze if source/target type mismatch, suggest type assertion or wrapper |
| Behavioral difference detected |
Flag to user with before/after examples, get approval |
| Tests still fail after 3 iterations |
Present failure analysis, ask user how to proceed |
| /tmp write fails |
Fall back to subagent review |
Reference Files
- package-managers.md — Detection matrix and commands
- repo-conventions.md — Convention detection and compliance
- confidence-index.md — Confidence index specification
- context7-integration.md — Context7 MCP detection and usage
- migration-patterns.md — Methodology and common patterns
Notes
- Requirements:
gh CLI (for releases API), package manager CLI
- Context7: Optional but recommended; install through the current agent's plugin or MCP setup flow.
- Supported ecosystems: npm, pnpm, yarn, bun, cargo, pip/uv/poetry, go, bundler, composer
- Limitations: Private registry auth requires manual setup; no auto-handling of 2FA prompts
- Monorepos: Detected automatically, but user may need to specify target package for large workspaces
- Boundary: Use this skill when replacing one library with another or migrating API patterns. For version bumps (A v1 → A v2), use
deps-upgrade instead.
1---2name: deps-migrate3description: >-4 Replace one library with another (e.g., moment.js to date-fns, webpack to vite),5 or migrate deprecated API patterns within the same library (e.g., React 19 forwardRef6 removal, Vue 3 Options API to Composition API). Use when asked to "replace X with Y",7 "migrate from X to Y", "switch from X to Y", "swap X for Y", "convert from X to Y",8 "port from X to Y", "remove deprecated forwardRef", "migrate to new API",9 or when planning library replacement or API migration. Also trigger when the user10 mentions switching libraries, finding alternatives, or removing deprecated patterns.11 Boundary: for replacing libraries or migrating API patterns. Use deps-upgrade for12 version bumps within the same library.13metadata:14 source: https://skillmd.com/skills/vdustr/deps-migrate15---1617# Dependency Migration1819Replace one library with another, or migrate deprecated API patterns within the same library.2021## Quick Start2223> Replace moment.js with date-fns2425> Migrate from webpack to vite2627> Remove deprecated forwardRef usage (React 19)2829> Switch from lodash to es-toolkit3031> Migrate Vue Options API to Composition API3233## Scope3435| Type | Example | Trigger |36|------|---------|---------|37| **Library replacement** | moment.js → date-fns | "replace X with Y" |38| **API pattern migration** | React 19 forwardRef removal | "remove deprecated X", "migrate to new Y API" |3940Both types follow the same test-first workflow below.4142## Workflow4344> **Non-linear execution**: Phases are numbered for reference, not strict order. If findings in any phase invalidate earlier assumptions, restart from the affected phase.4546### Phase 1: Environment Analysis4748- Detect package manager from lockfile (see [package-managers.md](references/package-managers.md))49- Detect monorepo structure50- Detect CI, hooks, changeset config (see [repo-conventions.md](references/repo-conventions.md))51- Detect test infrastructure (test runner, tsconfig.json, linter)5253### Phase 2: Identify Migration Target5455**For library replacement:**56- Parse source library (to remove) and target library (to add)57- Detect current usage scope: grep for imports/requires of source library58- Count affected files and usage patterns5960**For API pattern migration:**61- Identify deprecated/removed API pattern62- Scan all occurrences in codebase63- Identify the replacement pattern from docs6465### Phase 3: Documentation & Compatibility Analysis6667Consult all sources (use subagents for parallel lookup when possible; see [context7-integration.md](references/context7-integration.md)):681. **Context7** → Query both libraries for API comparison, migration guides692. **Community resources** → Search for known migration guides703. **Code analysis** → Map source API usage to target equivalents7172**Conflict resolution**: If sources disagree on API equivalence or behavior, use the most conservative conclusion and flag the discrepancy.7374Build an API mapping table:7576| Source | Target | Notes |77|--------|--------|-------|78| `moment().format('YYYY')` | `format(date, 'yyyy')` | Different format tokens |79| `React.forwardRef((props, ref) => ...)` | `function Component({ ref, ...props })` | ref is now a regular prop |8081See [migration-patterns.md](references/migration-patterns.md) for methodology and common patterns.8283### Phase 3.5: Official Tools & Compat Layer Detection8485Check for official/community migration tools **before** writing custom migrations:8687**For library replacement:**88- **Compat layer** — e.g., `es-toolkit/compat` for lodash89 - Ask user: "Use compat for gradual migration, or full replacement?"90 - Compat-first: swap import paths → verify → optionally migrate to native API later91- **Codemods** — e.g., `jscodeshift` transforms from library authors9293**For API pattern migration:**94- **Official codemods** — e.g., `npx react-codemod rename-unsafe-lifecycles`95- **Framework CLI migration** — e.g., `npx @angular/cli update`, `npx storybook automigrate`9697Decision flow:98- **Codemod exists** → run codemod first, handle remaining manually99- **Compat layer available** → ask user preference (gradual vs full)100- **Neither** → proceed to Phase 4101102### Phase 3.7: Related Package Detection103104**For library replacement:**105- Check if `@types/<source>` exists → should be removed (scoped: `@scope/pkg` → `@types/scope__pkg`)106- Check if target requires `@types/<target>` or companion packages107- For each related package found, also check for its `@types/` counterpart (e.g., react-dom → @types/react-dom)108- Check for related plugins/adapters referencing the source library109110**For API pattern migration:**111- Usually no related packages needed, but check for community wrappers112113Present findings and ask user whether to include.114115### Phase 4: Test-First Verification116117Validate the migration approach **before** batch execution.1181191. **Scan all usage** — comprehensive grep for all patterns to migrate1202. **Write test diffs in /tmp** — pick representative examples (not all files):121 - Select 2-3 diverse usage patterns (simple, complex, edge case). If more than 10 distinct patterns exist, sample at least 30% and reflect actual coverage in the confidence index122 - Create migrated versions in /tmp123 - Run type check + tests against migrated snippets124 ```125 /tmp/deps-shift-verify-<package>-<timestamp>/126 ├── package.json # Minimal deps (target package only)127 ├── tsconfig.json # Copied from project, paths/aliases adjusted for /tmp128 ├── original/ # Copy of affected code snippets129 ├── migrated/ # Proposed migration applied130 └── test-runner.sh # Must run tsc --noEmit at minimum, must NOT be just exit 0131 ```132 **Environment setup**: Create a minimal `package.json`, install only the target package version fresh. Copy project's `tsconfig.json`; remove `paths`, `baseUrl`, and `references` fields that point to project-specific locations — /tmp resolves modules through its own `node_modules` only. Never mutate the project's actual `node_modules`.1333. **Verify approach works** before committing to full migration1344. **Pass** → proceed to Phase 51355. **Fail** → iterate (max 3 attempts), then present failure analysis136137**Fallback**: When tests can't be written → subagent 3-pass review loop:138- Pass 1 (Direct): correctness of API mapping, import resolution139- Pass 2 (Best Practice): idiomatic target library usage140- Pass 3 (Critical Think): edge cases, behavioral differences, risks141- Fix + loop until all passes clean142143### Phase 5: Migration Plan & Confidence Index144145Present structured plan with [confidence index](references/confidence-index.md):146- File-by-file change summary147- API mapping table (validated by Phase 4)148- Potential issues / no direct equivalent149- Confidence index with factor breakdown and boost options150- Repo convention actions151152**Always get user confirmation before executing.**153154### Phase 6: Execute Migration1551561. Install target library (if library replacement)1572. Apply transformations file by file using validated mapping1583. **Checkpoint**: Verify all files have been transformed — grep for remaining source library imports. If any remain, do NOT proceed to removal1594. **Check for peer dependency conflicts** — present options if found1605. Clean up unused imports/types1616. Clean up /tmp verification files162163**Note**: Source library removal happens in Phase 8 **after** final verification passes. Do NOT remove it here — keeping it installed during verification ensures rollback is possible if issues are found.164165### Phase 7: Repo Convention Compliance166167Detect and follow project conventions (see [repo-conventions.md](references/repo-conventions.md)):168- Changesets → create changeset file169- Conventional commits → follow format170- CI checks → run matching local commands171- Pre-commit hooks → ensure hooks pass172- Custom scripts → run test, lint, typecheck173174### Phase 8: Final Verification1751761. Type check → 2. Lint → 3. Test suite → 4. Build1775. For complex migrations: run subagent Pass 3 (Critical Think) as final quality gate1786. **After all checks pass**: Remove source library from `package.json` (if library replacement). If source is a transitive dep of other packages, it stays in lockfile — only remove the direct dependency1797. Run install to update lockfile after removal180- All pass → report success181- Failures → analyze if migration-related, attempt fix, present remaining to user (source library is still installed, so rollback is straightforward)182183## Guidelines184185### DO186187- **Build a complete API mapping table** — map every source API to target equivalent before migrating188- **Check for official codemods first** — search npm registry and migration guides before writing custom transforms189- **Offer compat layers when available** — ask user preference (gradual vs full), never assume190- **Test migration approach in /tmp first** — validate on representative samples before batch191- **Use Context7 for both libraries** — query source and target library docs in parallel192- **Handle "no equivalent" cases** — ask user, implement custom wrapper, or document manual step193- **Always confirm before execution** — present migration plan, get user approval194- **Follow repo conventions** — detect and comply with changesets, commit format, CI checks195196### DON'T197198- **Skip codemod detection** — always check for official tools first199- **Skip test-first verification** — never execute batch migration without validating approach200- **Remove source library prematurely** — verify all usage migrated before removing201- **Assume API equivalence** — subtle behavioral differences exist (async vs sync, shallow vs deep copy)202- **Force migration when tests fail** — present failure analysis, let user decide203- **Assume compat layer preference** — always ask user (gradual vs clean break)204- **Migrate test files last** — migrate tests alongside implementation to catch issues early205206## Error Handling207208| Error | Action |209|-------|--------|210| No direct API equivalent found | Document gap, ask user for custom wrapper or alternative approach |211| Codemod crashes partway | Report progress, show transformed files, suggest manual completion |212| Context7 MCP tool not found | Suggest installation, continue with community guides + code analysis |213| Type errors after migration | Analyze if source/target type mismatch, suggest type assertion or wrapper |214| Behavioral difference detected | Flag to user with before/after examples, get approval |215| Tests still fail after 3 iterations | Present failure analysis, ask user how to proceed |216| /tmp write fails | Fall back to subagent review |217218## Reference Files219220- [package-managers.md](references/package-managers.md) — Detection matrix and commands221- [repo-conventions.md](references/repo-conventions.md) — Convention detection and compliance222- [confidence-index.md](references/confidence-index.md) — Confidence index specification223- [context7-integration.md](references/context7-integration.md) — Context7 MCP detection and usage224- [migration-patterns.md](references/migration-patterns.md) — Methodology and common patterns225226## Notes227228- **Requirements**: `gh` CLI (for releases API), package manager CLI229- **Context7**: Optional but recommended; install through the current agent's plugin or MCP setup flow.230- **Supported ecosystems**: npm, pnpm, yarn, bun, cargo, pip/uv/poetry, go, bundler, composer231- **Limitations**: Private registry auth requires manual setup; no auto-handling of 2FA prompts232- **Monorepos**: Detected automatically, but user may need to specify target package for large workspaces233- **Boundary**: Use this skill when replacing one library with another or migrating API patterns. For version bumps (A v1 → A v2), use `deps-upgrade` instead.