🧭 React Migration Edition: How to Transition from Knowing to Planning a Migration
Unclass
🌟 Introduction
This is the third article from the Unclass team, written with a strong sense of mentorship and care. In our last post, we discussed whether switching from class-based to functional components in React is the right choice. If you're here, you've likely decided that the migration is worthwhile. That's an important and thoughtful decision.
However, just like a craftsman doesn't start cutting wood without a plan, your next question should be: how will we do this correctly?
In this article, we’ll guide you in making two key decisions: choosing the right migration model and selecting an agile methodology that suits your team and situation. These choices can save you months of headaches—or cause them if made too quickly.
🧩 Assessing Your Starting Point
Before jumping into strategies, take a pause and reflect with your team:
How many developers are available?
What’s their seniority and experience with modern React?
What’s the deadline or delivery window?
How complex, coupled, or brittle is the current codebase?
This isn’t busywork. This is architectural awareness. Your answers will shape everything that follows.
🏗️ Choosing Your Migration Model
Let’s break down your options with honesty and care:
🔧 Refactoring
When to use it: The codebase works reasonably well, and your goal is maintainability—not rebuilding.
Approach: Gradually convert class components to functions during regular development. Think like a gardener pruning overgrown branches while keeping the tree alive.
Ideal for: Teams that are actively shipping features, working in a stable environment, or don’t have the capacity for a full rewrite.
Bonus: Emphasizes craftsmanship—“leave the code better than you found it.”
"Refactoring is a disciplined technique for restructuring an existing body of code, altering its internal structure without changing its external behavior." — Martin Fowler
🧱 Rebuilding
This is when you need a fresh start, but it comes with significant trade-offs.
✳ By Blocks (Modular Rewrite)
Migrate component groups or feature domains gradually.
Maintain bridges between legacy and new parts.
Allows for testing each new part in isolation.
🆕 From Scratch (Greenfield)
Start a brand-new project with modern principles.
Useful when the legacy system is too broken to salvage.
Risky: Total rewrites often lead to underestimated timelines and forgotten edge cases.
"The big rewrite is one of the most dangerous moves in software. You're throwing away known behavior in exchange for hope." — Joel Spolsky
🧭 Selecting Your Agile Methodology
Migrations don't happen on their own. They need rhythm, structure, and routines. Let's discuss methodologies that help organize teams, not just track tickets.
We'll focus on team-level frameworks that shape how people collaborate—not just visual tools like Kanban, which can be added to any of these frameworks.
🌀 Extreme Programming (XP)
Best for: Small, senior teams working under high urgency or with high standards.
Core Values: Communication, simplicity, feedback, courage, respect.
Practices: Test-driven development (TDD), pair programming, continuous integration, shared code ownership.
Why it fits: Encourages small, safe iterations with constant validation. Perfect for refactoring or modular rebuilds.
"XP is about delivering value quickly and consistently, while keeping the code clean and sustainable." — Kent Beck
🧱 Feature-Driven Development (FDD)
Best for: Large teams with clear business requirements and long-term roadmaps.
Phases: Develop overall model → Build feature list → Plan by feature → Design by feature → Build by feature.
Why it fits: Breaks the project into business-focused slices, which works well when rebuilding by domain.
Limitation: Assumes that features are well-defined upfront—less flexible to changing requirements.
🍃 Lean Software Development
Best for: Teams looking to minimize waste and focus on continuous improvement.
Principles: Eliminate waste, amplify learning, defer commitment, deliver fast, build integrity in, empower the team, see the whole.
Why it fits: Keeps your migration lightweight, deliberate, and focused on long-term outcomes.
🔮 Crystal
Best for: Small teams that value flexibility over process.
Philosophy: The team adapts the methodology to their needs, not the other way around.
Why it fits: Migration projects often evolve—Crystal gives room for teams to tailor their pace and practices.
"Crystal is based on the recognition that every project is different and the people involved are the most important factor." — Alistair Cockburn
✅ Summary
Once you know you need to migrate, take a breath. Don’t just run to the code. Instead, create a plan that respects your people, your timeline, and the code’s complexity.
Refactor if you can evolve your system steadily.
Rebuild if the old system is beyond saving—but rebuild wisely.
Choose XP if your team is senior and tight-knit.
Choose FDD or Lean if you need structured deliverables.
Use Crystal if you need freedom to adapt.
Whatever you choose, remember: you are not just migrating code—you’re guiding a team through change.
"The code we write is a reflection of our values. Migration is a chance to reaffirm them." — Unclass Team
In the next article, we’ll explore practical migration rhythms and edge-case patterns you can use once you’ve picked a direction.
Stay tuned—and refactor responsibly. 🚀
📚 References
🔄 Refactoring in Software Development
🏗️ Rebuilding (By Blocks and From Scratch)
📈 Choosing the Right Agile Methodology
🌀 Extreme Programming (XP)
🧩 Feature-Driven Development (FDD)
🧠 Lean Software Development
💎 Crystal Methodology
This article is written as a letter from one software craftsman to another. Let it guide your path, save you from avoidable mistakes, and remind you that migrations—done right—are not burdens, but opportunities to rebuild trust, quality, and joy in your code.
Subscribe to my newsletter
Read articles from Unclass directly inside your inbox. Subscribe to the newsletter, and don't miss out.
Written by
Unclass
Unclass
We're building tools that help teams migrate from React class components to functional components — starting with free education, moving toward powerful automation. Creator of Unclass, a CLI and analyzer to bring legacy code into the modern React era. I write weekly about React migration, code transformation, and automation with TypeScript.