Frontend migration risks and how to reduce them
Many migration problems trace back to scope, surprises and people. This guide lists the risks that matter, how to spot them early and what to do about each one.
A risk register you can copy
| Risk | Early signal | Main mitigation |
|---|---|---|
| Scope creep | "While we are here, let's also..." | A written rule: migrate first, improve later |
| Regressions | Bugs reported in screens that were just migrated | Tests on critical flows, flags, fast rollback |
| Hidden business rules | Nobody can explain why a field behaves a certain way | Characterization tests, parity review with a business user |
| Key-person dependency | All questions go to the same person | Pairing, documentation, shared ownership |
| Hybrid forever | Legacy share stops falling | Deletion in the definition of done, a funded cleanup phase |
| Loss of sponsorship | Checkpoint meetings get cancelled | Visible results in every phase, a monthly report |
The sections below explain the first four in detail, because they cause the most damage.
Scope creep
A migration opens every screen of the product. Each one invites improvements: a better layout, a cleaner flow, a field that someone always wanted. Each improvement looks small. Together they turn a migration with a known size into a redesign with no end.
What to do
- State the rule at the start: same layout, same behavior. Stakeholders sign off on it.
- Keep a separate list for improvement ideas. Product prioritizes them after the screen is migrated.
- Allow one category of exception: fixing a bug is acceptable when keeping it would cost more than removing it. Record each case.
- Review scope at every checkpoint. If a phase grew, say so and re-estimate.
Regressions
Users judge the migration by whether their daily work still functions. A few visible bugs in a migrated screen can cost the program its credibility.
What to do
- Write end-to-end tests for the critical flows against the legacy app before migrating them. The same tests then verify the new version.
- Release each screen behind a switch, to a small group first. See feature flags in an incremental migration.
- Monitor frontend errors per screen and per version, so a rise is visible within minutes.
- Rehearse the rollback during the pilot. A rollback that was never tested is a hope.
- Keep the legacy version for a short, fixed period after release. Then delete it.
Hidden business rules
Old frontends contain rules that exist nowhere else. A discount applied only for one customer type. A field that becomes mandatory on the last day of the month. A rounding choice made years ago. They live in controllers and templates, without tests or documents, and the person who wrote them may be gone.
What to do
- Read the template and the controller of every screen before estimating it. Conditions in the markup are rules.
- Write characterization tests: tests that record what the code does today, whether or not anyone can explain it.
- Run a parity review with someone who uses the screen daily. They notice what a developer misses.
- When a rule looks wrong, ask before "fixing" it. Somebody may depend on it.
- Move each discovered rule into a named, tested function in the new code. The migration then leaves the rules better documented than it found them.
Key-person dependency
There are usually one or two people who understand the legacy app. The migration needs their knowledge every day, and they are also needed for production issues and features. If one of them leaves or burns out, the work stops.
The same risk appears on the other side. If a single migration specialist, internal or external, holds all the knowledge of the new architecture, you have replaced one dependency with another.
What to do
- Schedule the experts' time explicitly. A fixed weekly slot for questions works better than interruptions.
- Record the answers. A short written note per module is enough.
- Pair developers on migrated screens so at least two people know each area.
- Document the patterns of the new code: how a screen is structured, how state is shared, how to add a route.
- Rotate who reviews pull requests.
Risks that grow quietly
Hybrid forever. The migration reaches most of the app and loses momentum. The remaining legacy screens are the hardest ones, and the budget is gone. Prevent it by scheduling at least one hard module early and by funding the cleanup from the start.
Parallel feature work. Features and migration collide in the same module. The guide on keeping teams shipping covers the freeze rules that prevent it.
How to review risks
Keep the register short and look at it every month. For each risk note the signal you are watching, the owner and the current status. Include it in the progress report described in measuring migration progress. A risk that is written down and reviewed rarely becomes a surprise.
More in this section
- The strangler fig pattern applied to frontends
- Feature flags and route switches in an incremental migration
- Leaving AngularJS: Angular or React?
- Migrating a jQuery-heavy app to a component framework
Planning a migration or a micro-frontend platform?
In a 20-minute call you describe your situation and I tell you how I'd approach it. If it isn't worth doing yet, I'll say so.
Message me on LinkedIn