Agent skill

migration-assistant

Expert in code migrations, version upgrades, breaking change handling, automated codemods, deprecation warnings, and migration testing

Stars 163
Forks 31

Install this agent skill to your Project

npx add-skill https://github.com/majiayu000/claude-skill-registry/tree/main/skills/development/migration-assistant

SKILL.md

Migration Assistant

Expert skill for handling code migrations and version upgrades. Specializes in codemods, breaking change detection, automated migrations, and upgrade strategies.

Core Capabilities

1. Version Migrations

  • React Upgrades: v16 → v17 → v18
  • Dependency Updates: Major version changes
  • Breaking Changes: Identify and fix
  • Deprecation Warnings: Replace deprecated APIs
  • Migration Guides: Step-by-step instructions

2. Codemods

  • jscodeshift: AST transformations
  • Custom Transforms: Project-specific migrations
  • Batch Updates: Update multiple files
  • Safe Migrations: Test before apply
  • Rollback: Undo if needed

3. Pattern Migrations

  • Component Patterns: Class → Function
  • State Management: Context → Zustand/Redux
  • Styling: CSS → Tailwind/CSS-in-JS
  • Build Tools: Webpack → Vite
  • Testing: Enzyme → Testing Library

4. Breaking Change Detection

  • API Changes: Detect usage of changed APIs
  • Prop Changes: Component API updates
  • Import Changes: Module resolution
  • Type Changes: TypeScript migrations

React 18 Migration

typescript
// React 18 Codemod
// Class component → Function component with hooks

// Before (React 16/17)
class Counter extends React.Component {
  state = { count: 0 }

  increment = () => {
    this.setState({ count: this.state.count + 1 })
  }

  render() {
    return (
      <div>
        <p>{this.state.count}</p>
        <button onClick={this.increment}>+</button>
      </div>
    )
  }
}

// After (React 18)
function Counter() {
  const [count, setCount] = useState(0)

  const increment = () => {
    setCount(count + 1)
  }

  return (
    <div>
      <p>{count}</p>
      <button onClick={increment}>+</button>
    </div>
  )
}

// React 18 Root API
// Before
import ReactDOM from 'react-dom'
ReactDOM.render(<App />, document.getElementById('root'))

// After
import { createRoot } from 'react-dom/client'
const root = createRoot(document.getElementById('root')!)
root.render(<App />)

Codemod Example

typescript
// codemod/class-to-function.ts
import { Transform } from 'jscodeshift'

const transform: Transform = (file, api) => {
  const j = api.jscodeshift
  const root = j(file.source)

  // Find class components
  root.find(j.ClassDeclaration).forEach(path => {
    const className = path.value.id.name

    // Convert to function component
    const functionComponent = j.functionDeclaration(
      j.identifier(className),
      [],
      j.blockStatement([
        // Add hooks based on state and lifecycle
        // ... transformation logic
      ])
    )

    j(path).replaceWith(functionComponent)
  })

  return root.toSource()
}

export default transform

// Run codemod
// npx jscodeshift -t codemod/class-to-function.ts src/

Migration Checklist

markdown
# React 18 Migration Checklist

## Pre-migration
- [ ] Audit current React version
- [ ] Read React 18 migration guide
- [ ] Update TypeScript to 4.5+
- [ ] Backup codebase
- [ ] Run current tests

## Dependencies
- [ ] Update react to 18.x
- [ ] Update react-dom to 18.x
- [ ] Update @types/react
- [ ] Update testing library
- [ ] Check all dependencies compatibility

## Code Changes
- [ ] Update root rendering API
- [ ] Replace deprecated APIs
- [ ] Add types for new features
- [ ] Update tests
- [ ] Fix TypeScript errors

## Testing
- [ ] Run unit tests
- [ ] Run integration tests
- [ ] Manual QA testing
- [ ] Performance testing

## Post-migration
- [ ] Update documentation
- [ ] Train team on new features
- [ ] Monitor production
- [ ] Clean up deprecated code

Deprecation Warning System

typescript
// utils/deprecation.ts
export function deprecationWarning(
  oldAPI: string,
  newAPI: string,
  version: string
) {
  if (process.env.NODE_ENV === 'development') {
    console.warn(
      `[Deprecation] ${oldAPI} is deprecated and will be removed in v${version}. ` +
      `Please use ${newAPI} instead.`
    )
  }
}

// Usage
function OldComponent(props: Props) {
  deprecationWarning('OldComponent', 'NewComponent', '2.0.0')
  return <div>{/* ... */}</div>
}

Breaking Change Detection

typescript
// scripts/detect-breaking-changes.ts
import { Project } from 'ts-morph'

const project = new Project()
project.addSourceFilesAtPaths('src/**/*.{ts,tsx}')

const breakingChanges = []

// Detect usage of deprecated APIs
project.getSourceFiles().forEach(sourceFile => {
  const deprecatedAPIs = sourceFile
    .getDescendantsOfKind(ts.SyntaxKind.CallExpression)
    .filter(call => {
      const name = call.getExpression().getText()
      return DEPRECATED_APIS.includes(name)
    })

  if (deprecatedAPIs.length > 0) {
    breakingChanges.push({
      file: sourceFile.getFilePath(),
      apis: deprecatedAPIs.map(api => api.getText()),
    })
  }
})

console.log('Breaking changes found:', breakingChanges)

Best Practices

  • Read migration guides thoroughly
  • Test migrations on a branch
  • Update dependencies incrementally
  • Use codemods for repetitive changes
  • Keep comprehensive test coverage
  • Document breaking changes
  • Communicate with team
  • Monitor after migration

When to Use This Skill

Use when you need to:

  • Upgrade React or dependencies
  • Migrate between libraries
  • Handle breaking changes
  • Create codemods
  • Automate code transformations
  • Deprecate old APIs
  • Guide team through migrations

Output Format

Provide:

  1. Migration Plan: Step-by-step guide
  2. Codemods: Automated transformations
  3. Breaking Changes: What changed
  4. Testing Strategy: Ensure nothing breaks
  5. Documentation: Update guides
  6. Rollback Plan: If things go wrong

Expand your agent's capabilities with these related and highly-rated skills.

Didn't find tool you were looking for?

Be as detailed as possible for better results