Migraties van code en frameworks
Op deze pagina
Veilig migreren met Codex
Migraties van frameworks, bibliotheken en grote versies behoren tot de riskantste taken in de ontwikkeling: ze hebben invloed op het hele project in één keer, kunnen niet half worden uitgevoerd en vallen altijd op het slechtst mogelijke moment van het kwartaal. Codex reduceert een migratie die meerdere dagen zou duren tot enkele uren door API-wijzigingen en incompatibiliteiten systematisch af te handelen—precies dat onderdeel waarbij de menselijke aandacht rond bestand dertig begint te verslappen.
Framework-migraties
Het overschakelen naar een ander framework is het meest ambitieuze scenario en meestal het scenario dat eindigt als een verlaten project in een ticket van twee jaar oud.
"Migrate the application from Express.js to Fastify.
The project uses Express with:
- 15 routes in src/routes/
- JWT authentication middleware
- Morgan logging middleware
- CORS middleware
- Centralized error handling
Migrate route by route, preserving existing tests."
De inventarisatie bovenaan de prompt is geen decoratie: deze garandeert dat er geen middleware wordt vergeten. Codex gaat vervolgens stap voor stap te werk: het analyseert de bestaande Express-configuratie, maakt de equivalente Fastify-configuratie, migreert elke route met aangepaste syntaxis, wisselt middlewares om voor hun equivalenten, werkt tests bij en verifieert dat alles slaagt. De instructie “route by route” levert als bonus een leesbare diff op, waarbij elke route geïsoleerd kan worden beoordeeld zonder door de andere veertien te hoeven scrollen.
Migraties van grote versies
Grote versie-upgrades komen vaker voor, maar zijn niet minder lastig omdat brekende wijzigingen verspreid zijn in plaats van geconcentreerd.
"Migrate the project from React 18 to React 19.
Key points:
- Replace forwardRef with native ref props
- Migrate useContext usage to the new pattern
- Update TypeScript types (@types/react)
- Verify third-party library compatibility"
Codex baseert zich op de officiële migratienotities in zijn context en past wijzigingen systematisch toe. Neem de tijd om deze kernpunten zelf te formuleren: ze sturen de zoekopdracht tijdens de uitvoering en dienen als uw checklist tijdens de review, wat de waarde verdubbelt.
Database-migraties
Bij wijzigingen in het schema ligt de moeilijkheid nooit in de SQL-migratie zelf, maar in alle applicatiecode die ervan afhankelijk is.
"The User model needs restructuring:
- Separate address into an Address model (1-N relationship)
- Rename email to primaryEmail
- Add an optional phone field
- Create the Prisma migration
- Update all services and routes using User
- Update tests"
Codex behandelt alle drie de lagen in één taak: het Prisma-schema, de SQL-migratie en alle referenties in de applicatie. Een simpele hernoeming van email naar primaryEmail raakt doorgaans ongeveer dertig bestanden, waaronder enkele die een naïeve tekstzoekopdracht niet vindt—een dynamisch opgebouwd veld, een serialisatiesleutel, een sorteertoewijzing.
Bibliotheek-migraties
Het vervangen van de ene bibliotheek door de andere vereist dat u expliciet benoemt wat invariant moet blijven.
"Replace moment.js with date-fns throughout the project.
Ensure that:
- All date formats are preserved
- Duration calculations remain correct
- Date comparisons work properly
- Time zones are handled the same way"
Het punt over tijdzones redt datum-migraties: twee bibliotheken kunnen op uw machine identieke output produceren en op een UTC-server een uur verschillen. Bij dit soort werk wordt de schaal van de winst duidelijk in de onderstaande tabel.
| Veelvoorkomende migratie | Handmatige duur | Duur met Codex |
|---|---|---|
| JavaScript naar TypeScript | 1-2 weken | 2-4 uur |
| REST naar GraphQL | 2-3 weken | 1-2 dagen |
| Webpack naar Vite | 2-5 dagen | 2-4 uur |
| moment.js naar date-fns | 1-3 dagen | 30 minuten - 2 uur |
Strategie voor gefaseerde migratie
Deze tijdsduur gaat uit van een uitvoering in één keer, wat alleen redelijk is voor bescheiden projecten. In alle andere gevallen splitst u het op. Een bewust beperkte eerste fase legt de conventies vast die volgende fasen zullen volgen:
"Phase 1: Migrate only src/lib/ from JavaScript to
strict TypeScript. Do not touch React components or
API routes. Add necessary types and fix typing errors."
Zodra deze fase is gevalideerd en samengevoegd, bouwt de volgende er expliciet op voort:
"Phase 2: Migrate src/components/ from JavaScript to
strict TypeScript. Use the same typing patterns as
src/lib/ (phase 1 already migrated)."
Het voordeel is tweeledig. Het risico blijft beperkt, omdat een mislukte fase kan worden teruggedraaid zonder de rest van het werk ongedaan te maken. En elke fase levert een pull request op die een mens daadwerkelijk kan reviewen—een doorslaggevend criterium, want een migratie die als een enkele diff van zeshonderd bestanden wordt aangeleverd, wordt niet gereviewd; deze wordt uit putte goedkeuring verleend, waardoor het grootste deel van het verwachte voordeel teniet wordt gedaan.
Belangrijkste punten
- Migraties zijn de taken waarbij Codex de grootste productiviteitswinst oplevert
- Neem de kernpunten die specifiek zijn voor uw project op in uw instructies
- Werk bij grote migraties in gefasen
- Codex werkt code, tests en afhankelijkheden in één taak bij
- Verifieer na een migratie altijd met een volledige build en tests