I recently led a team through a major web app migration—from Vue 2 + Bootstrap 3 to Vue 3 + Bootstrap 5. It was a long, messy, valuable project. We made mistakes, learned a lot, and came out stronger.
Here are five things I wish I knew before we started. I’m sharing them in case you’re planning (or stuck in) a big migration of your own.
1. Decide if it’s big bang or incremental
This is the first call you need to make. Can you migrate the app piece by piece while still shipping features? Or is it a “stop everything and upgrade” situation?
If it’s a big framework or architecture change, you might have no choice but to go all-in. In our case, mixing Vue 2 and Vue 3 wasn’t safe, so it had to be a full cutover. That shaped everything—from how we scoped work to how we tested and released it.
If you can do it incrementally – do it! It’s less risky and easier to plan round other projects. But make that decision early. Don’t discover halfway in that you need to change your approach.
2. Avoid mixing migration work with feature work
Trying to ship features and migrate at the same time is a bad idea. We tried. It slowed us down and made everything harder to test.
Migration work is invisible. It doesn’t show up in user-facing demos. That means it often gets pushed down the backlog if you’re not careful. Features will always feel more urgent.
Ideal approach: block a few sprints to focus only on migration. No new features (code freeze with maybe minimal urgent bug fixes). Just cleanup, refactors, and updates. That would allow avoiding wasted work (and even double work in some cases) and help the team focus and actually get things done.
3. Give your QA enough time
We underestimated the amount of regression testing needed. So make sure you plan pessimistically and give your QA enough time upfront.
Framework migrations often break things in weird ways. Components render differently. Event handling changes. Styles shift. Tests break. Libraries need replacement. Even with good unit tests, stuff can go wrong.
Give QA dedicated time and space in the schedule. Avoid overlapping regression testing with other feature testing (we used this time to work on various technical projects that don’t require QA capacity like optimizing pipelines, working on POCs etc.). And be clear about what changed and what didn’t—don’t make them guess.
4. Clean up as you go
It’s tempting to just focus on getting the new version working. But if you don’t clean up while you’re in there, you’ll finish the migration and still have a mess.
You may want to delete unused files and simplify component code as you work on the migration. That can make things easier to test and maintain. It also gives the team a sense of progress.
This also means: don’t migrate something you don’t plan to keep. If a feature or component is outdated, just remove it. Less code means fewer bugs. And you’d still have to do a regression testing on everything, so why not use this opportunity and incorporate some refactors.
5. Scope it better than you think you need to
We thought this would take 2 months. It took almost 2 years. Part of that is normal. Migration work is tricky and unpredictable, and as we all know urgent/important business requests come in and things have to be put on pause. But part of it was poor scoping.
We didn’t fully analyze what would be affected. We didn’t plan for the effort it would take to test and stabilize everything. We also underestimated how much this work would overlap with other projects.
Next time, I’ll do a full system audit before kicking off. That means:
- listing all components and features
- mapping out what libraries need to change
- checking for blockers (e.g., incompatible packages)
- estimating time for regression and stabilization
Also, I’ll flag migration as a first-class initiative in our roadmap—not something squeezed in on the side and worked on “in the background”.
Final thoughts
A big migration is like fixing the engine of a moving car. It takes focus, planning, and a lot of coordination. But it’s also a great chance to improve your codebase and your team’s habits.
If you’re leading a migration soon, I hope these lessons help you avoid some of our early mistakes. And if you’re in the middle of one: hang in there. Finish strong, clean up as you go, and write down what you’ve learned.
Your future self and your team will thank you.