opencodemigraciónlegacymodernizaciónrefactor

Migración de Proyectos con OpenCode: Estrategias y Casos Prácticos

Por Binary Core

Las migraciones de proyectos son riesgosas y costosas. OpenCode puede reducir dramáticamente el riesgo y el tiempo: analiza el código existente, genera código migrado automáticamente, identifica breaking changes y mantiene la funcionalidad intacta durante el proceso.

Este tutorial asume que dominas el flujo Plan/Build, los refactors y la documentación. Aquí nos enfocamos en migraciones a gran escala.

Análisis Pre-Migración

Inventario de dependencias

[Plan Mode]

Analiza el proyecto @legacy-project/ y genera un inventario:

1. Lista todas las dependencias en package.json
2. Categoriza por:
   - Core dependencies (React, Next.js, etc.)
   - UI libraries
   - Utilities
   - Dev dependencies
3. Identifica dependencias:
   - Obsoletas/deprecated
   - Con vulnerabilidades de seguridad
   - Sin mantenimiento reciente
   - Con alternativas modernas

Genera un reporte con recomendaciones de actualización.

OpenCode generará:

markdown
# Dependency Analysis Report

## Core Dependencies
- React 17.2.0 → 18.3.0 (stable, recommended)
- Next.js 11.0.0 → 15.0.0 (major upgrade, breaking changes)
- TypeScript 4.3.0 → 5.5.0 (type system improvements)

## UI Libraries
- Material-UI 4.12.0 → MUI 5.15.0 (major upgrade)
- Styled-components 5.3.0 → 6.1.0 (performance improvements)

## Deprecated Dependencies
- ⚠️ classnames (use clsx + tailwind-merge instead)
- ⚠️ lodash (use native JS methods)
- ⚠️ axios-mock-adapter (use vi.mock in Vitest)

## Security Vulnerabilities
- 🚨 lodash < 4.17.21 (CVE-2021-23337)
- 🚨 axios < 0.21.1 (CVE-2021-3749)

## Recommendations
1. Update React and Next.js first (core)
2. Migrate from Material-UI to shadcn/ui (modern)
3. Remove lodash in favor of native methods
4. Update all security vulnerabilities

Análisis de complejidad

[Plan Mode]

Analiza la complejidad del proyecto para estimar esfuerzo:

Métricas:
- Número de archivos
- Líneas de código
- Complejidad ciclomática promedio
- Cobertura de tests
- Dependencias entre módulos

Clasifica archivos por:
- Riesgo de migración (alto/medio/bajo)
- Esfuerzo estimado (horas)
- Dependencias externas

Genera un plan de migración priorizado.

Migración de Frameworks

Next.js Pages Router → App Router

[Plan Mode]

Necesito migrar de Next.js 12 (Pages Router) a Next.js 15 (App Router).

Analiza @legacy-project/pages/ y genera plan:

1. Mapear cada página a app/[locale]/.../page.tsx
2. Convertir getServerSideProps a async Server Components
3. Migrar _app.js y _document.js a layout.tsx
4. Convertir API routes a app/api/.../route.ts
5. Migrar middleware al nuevo formato

Para cada archivo, especifica:
- Ruta antigua
- Ruta nueva
- Cambios necesarios
- Riesgo estimado

OpenCode propondrá:

markdown
# Next.js Migration Plan

## High Priority (Critical Routes)
- pages/index.tsx → app/[locale]/page.tsx
- pages/login.tsx → app/[locale]/login/page.tsx
- pages/dashboard.tsx → app/[locale]/dashboard/page.tsx

## Medium Priority (Feature Routes)
- pages/products/[id].tsx → app/[locale]/products/[id]/page.tsx
- pages/profile/[username].tsx → app/[locale]/profile/[username]/page.tsx

## Low Priority (Static Pages)
- pages/about.tsx → app/[locale]/about/page.tsx
- pages/contact.tsx → app/[locale]/contact/page.tsx

## API Routes
- pages/api/auth/*.ts → app/api/auth/*/route.ts
- pages/api/users/*.ts → app/api/users/*/route.ts

## Breaking Changes to Handle
- getInitialProps → data fetching in Server Components
- useRouter → useNavigation (new hook)
- next/image → new Image component API
- next/link → new Link component API

Create React App → Next.js

[Plan Mode]

Migrar de Create React App a Next.js 15:

Análisis:
- Estructura de carpetas actual
- Routing actual (React Router?)
- State management actual
- Build configuration
- Environment variables

Plan:
1. Crear proyecto Next.js
2. Migrar componentes a app/
3. Convertir routing a Next.js App Router
4. Migrar state management
5. Configurar build y deployment
6. Migrar tests

Genera pasos detallados para cada fase.

Migración de Lenguajes

JavaScript → TypeScript

[Plan Mode]

Migrar proyecto JavaScript a TypeScript:

Fase 1: Configuración
- Añadir tsconfig.json
- Configurar JSDoc para inferencia inicial
- Habilitar checkJs progresivamente

Fase 2: Migración incremental
- Migrar archivos uno por uno
- Empezar por tipos simples (utils, helpers)
- Terminar con componentes complejos

Fase 3: Tipado estricto
- Habilitar strict mode gradualmente
- Añadir tipos específicos
- Eliminar any types

Para cada archivo, genera:
- Código TypeScript equivalente
- Tipos necesarios
- Cambios breaking

OpenCode migrará:

javascript
// Antes (JavaScript)
export function calculateTotal(items) {
  return items.reduce((sum, item) => sum + item.price * item.quantity, 0);
}

export function findUser(users, id) {
  return users.find(user => user.id === id);
}
typescript
// Después (TypeScript)
interface Item {
  price: number;
  quantity: number;
}

interface User {
  id: string;
  name: string;
  email: string;
}

export function calculateTotal(items: Item[]): number {
  return items.reduce((sum, item) => sum + item.price * item.quantity, 0);
}

export function findUser(users: User[], id: string): User | undefined {
  return users.find(user => user.id === id);
}

Migración de State Management

Redux → Zustand

[Plan Mode]

Migrar de Redux Toolkit a Zustand:

Análisis:
- Redux slices existentes
- Actions y reducers
- Selectors
- Middleware
- Componentes que usan Redux

Plan:
1. Crear stores de Zustand equivalentes
2. Migrar reducers a actions de Zustand
3. Migrar selectors
4. Actualizar componentes
5. Eliminar Redux dependencies

Genera código de migración para cada slice.

typescript
// Antes (Redux Toolkit)
// store/userSlice.ts
const userSlice = createSlice({
  name: 'user',
  initialState: { user: null, loading: false },
  reducers: {
    setUser: (state, action) => {
      state.user = action.payload;
    },
  },
});

// Después (Zustand)
// store/useUserStore.ts
interface UserState {
  user: User | null;
  loading: boolean;
  setUser: (user: User) => void;
}

const useUserStore = create<UserState>((set) => ({
  user: null,
  loading: false,
  setUser: (user) => set({ user }),
}));

Migración de UI Libraries

Material-UI → shadcn/ui

[Plan Mode]

Migrar de Material-UI a shadcn/ui:

Análisis:
- Componentes MUI usados
- Custom themes
- Iconos
- Styling approach

Plan:
1. Instalar shadcn/ui
2. Migrar componentes uno por uno:
   - Button → Button
   - TextField → Input
   - Card → Card
   - Dialog → Dialog
3. Migrar theming a Tailwind
4. Actualizar iconos a lucide-react
5. Eliminar @mui/material

Para cada componente, genera código equivalente.

typescript
// Antes (Material-UI)
import { Button } from '@mui/material';

<Button variant="contained" color="primary" onClick={handleClick}>
  Click me
</Button>

// Después (shadcn/ui)
import { Button } from '@/components/ui/button';

<Button onClick={handleClick}>
  Click me
</Button>

Migración de Testing

Jest → Vitest

[Plan Mode]

Migrar de Jest a Vitest:

Cambios necesarios:
1. Actualizar package.json (vitest, @vitest/ui)
2. Configurar vitest.config.ts
3. Migrar mocks (vi.mock en lugar de jest.mock)
4. Actualizar assertions (expect de Vitest)
5. Migrar setup files
6. Actualizar scripts

Genera:
- Configuración completa de Vitest
- Ejemplos de migración de tests
- Comandos de actualización

typescript
// Antes (Jest)
import { render, screen } from '@testing-library/react';
import { jest } from '@jest/globals';

test('renders button', () => {
  render(<Button>Click</Button>);
  expect(screen.getByText('Click')).toBeInTheDocument();
});

// Después (Vitest)
import { render, screen } from '@testing-library/react';
import { describe, it, expect, vi } from 'vitest';

describe('Button', () => {
  it('renders button', () => {
    render(<Button>Click</Button>);
    expect(screen.getByText('Click')).toBeInTheDocument();
  });
});

Estrategias de Migración Segura

Strangler Fig Pattern

[Plan Mode]

Aplicar Strangler Fig Pattern para migración gradual:

Estrategia:
1. Dejar sistema antiguo funcionando
2. Crear nuevo sistema en paralelo
3. Migrar funcionalidad incrementalmente
4. Redirigir tráfico gradualmente
5. Eliminar sistema antiguo al final

Para este proyecto, genera:
- Qué funcionalidad migrar primero
- Cómo redirigir tráfico
- Cómo mantener compatibilidad
- Cómo monitorear durante migración

Feature Flags

[Plan Mode]

Usar feature flags para migración controlada:

Implementar:
1. Sistema de feature flags
2. Flags para cada funcionalidad migrada
3. Rollback instantáneo si hay problemas
4. Monitoreo de errores por flag
5. Gradual rollout por porcentaje

Genera:
- Implementación de feature flags
- Integración con código migrado
- Dashboard de monitoreo
- Proceso de rollback

Automatización de Migración

Scripts de migración

[Plan Mode]

Genera scripts de migración automatizada:

Script 1: Migración de imports
- Buscar imports antiguos
- Reemplazar con imports nuevos
- Actualizar paths

Script 2: Migración de componentes
- Buscar patrones de componentes antiguos
- Generar componentes nuevos
- Actualizar referencias

Script 3: Validación de migración
- Verificar que todo compile
- Ejecutar tests
- Reportar errores

Genera scripts en TypeScript que sean:
- Idempotentes
- Reversibles
- Con logging detallado
- Con reporte final

Monitoreo y Validación

Tests de regresión

[Plan Mode]

Generar tests de regresión para migración:

Antes de migrar:
1. Generar tests de caracterización del sistema actual
2. Capturar outputs de APIs
3. Capturar screenshots de UI
4. Guardar como baseline

Después de migrar:
1. Ejecutar mismos tests
2. Comparar outputs con baseline
3. Reportar diferencias
4. Validar que diferencias sean esperadas

Genera framework de tests de regresión.

Métricas de éxito

[Plan Mode]

Definir métricas para validar migración exitosa:

Métricas técnicas:
- Todos los tests pasan
- Performance no degrada (>10% aceptable)
- Sin errores en producción
- Coverage de tests se mantiene

Métricas de negocio:
- No hay regresiones visibles para usuarios
- Features funcionan igual
- No hay pérdida de datos

Genera dashboard de monitoreo con estas métricas.

Workflows de Migración

Workflow 1: Migración incremental

1. Análisis completo del proyecto
2. Plan de migración priorizado
3. Para cada módulo:
   a. [Plan Mode] Generar código migrado
   b. [Build Mode] Aplicar cambios
   c. Ejecutar tests
   d. Validar funcionalidad
   e. Commitear
4. Integration tests al final
5. Despliegue a staging
6. Monitoreo intensivo
7. Despliegue a producción

Workflow 2: Migración con feature flags

1. Implementar sistema de feature flags
2. Migrar código detrás de flags
3. Habilitar flags en desarrollo
4. Tests exhaustivos
5. Rollout gradual en producción:
   - 1% usuarios
   - 10% usuarios
   - 50% usuarios
   - 100% usuarios
6. Monitorear en cada etapa
7. Rollback si hay problemas
8. Eliminar flags al final

Workflow 3: Migración paralela

1. Crear nuevo proyecto en paralelo
2. Migrar funcionalidad incrementalmente
3. Mantener ambos sistemas funcionando
4. Redirigir tráfico gradualmente
5. Comparar outputs de ambos sistemas
6. Validar consistencia
7. Eliminar sistema antiguo
8. Limpiar código duplicado

Errores Comunes en Migraciones

ErrorCausaSolución
Big bang migrationIntentar migrar todo de golpeMigración incremental con feature flags
Sin tests de regresiónNo saber si algo se rompióGenerar tests de caracterización antes
Breaking changes no documentadosNo analizar cambios del frameworkDocumentar todos los breaking changes
Performance degradaNuevo framework más lentoMedir performance antes y después
Rollback difícilNo poder revertir cambiosMantener sistema antiguo hasta validar

Caso Práctico: Migración Real

[Plan Mode]

Caso: Migrar monolito Next.js 12 a Next.js 15 + shadcn/ui

Contexto:
- 50 páginas
- 200 componentes
- Redux para state
- Material-UI para UI
- 80% coverage de tests

Genera plan detallado con:
- Fases de migración
- Tiempo estimado por fase
- Riesgos y mitigaciones
- Puntos de decisión
- Criterios de éxito

OpenCode generará un plan de migración de 8 semanas con fases específicas, checkpoints y criterios de validación.

Conclusión

Migrar con OpenCode requiere:

  1. Análisis exhaustivo: Entender el sistema actual completamente
  2. Plan incremental: Dividir en cambios pequeños y verificables
  3. Automatización: Scripts para migración repetitiva
  4. Validación continua: Tests de regresión en cada paso
  5. Rollback capability: Siempre poder revertir cambios

En Binary Core, migramos un monolito de 100,000 líneas de Next.js 12 a Next.js 15 en 12 semanas con cero downtime y sin regresiones visibles para usuarios. La clave no es la velocidad, sino la disciplina: cada cambio probado, cada paso validado, cada rollback planificado.

Esta es la guía final de la serie OpenCode. Has aprendido desde la instalación hasta migraciones complejas. Ahora tienes las herramientas para usar OpenCode como un verdadero amplificador de tu capacidad como desarrollador.

Serie completa:

  1. Instalación y primeros pasos
  2. Flujo de trabajo Plan/Build
  3. Configuración avanzada
  4. Debugging
  5. Refactors
  6. Generación de tests
  7. Code review
  8. Workflows especializados
  9. Git workflows
  10. Documentación
  11. Migración de proyectos (este artículo)

Binary Core

Equipo Binary Core

← Volver al blog