Rewrite or Refactor? How to Safely Move Legacy Apps to Modern Frameworks

Hi everyone. Rewrite or refactor? Today I'm going to talk about something many teams face, but few prepare for. What to do when your frontend becomes legacy and how to migrate it safely. I'm Sylwia Laskowska, senior software developer at EITOS. I'm currently working on a large distributed project for the European Commission. I'm from Gdańsk, Poland. You can visit my blog where you can read more about frontend migrations and many, many more things.

And this won't be a tutorial talk. During my career, I had plenty of opportunities to see some, let's say, historically interesting code bases and give them a second life. I migrated apps from Backbone to Vue, from Old Angular to Modern Angular, from ASP.NPC.NET to Modern Frameworks. And honestly, after some time, you can start seeing the same migration patterns everywhere. And by the way, I have a lot of experience with legacy.

I created my first website in 1999. It looks somehow like this. HTML 4.1, a guest book, visits counter, frame sets, which were back then the greatest achievement of web design. No CSS, but who needs CSS when you can have falling JS snow in winter? So this one was perfect, and I would never migrate it. And back then, I thought this is the peak of software engineering. But then we had BackboneJS, KnockoutJS, and it was like, wow, finally, interactive UI, client-side form validation.

It felt like the future of the web. And then we had ECMAScript 6, TypeScript, Modern Frameworks, and suddenly, this future became legacy, again. Because the truth is, we will all end up with legacy just sooner or later. This is because tech ages faster than the business needs. And legacy doesn't always mean ancient or exotic. It can be perfectly normal tech, just old enough to stop scaling. For example, old versions of popular libraries. And of course, no one plans for legacy.

Maybe the project was paused for six years. Maybe no one has time or budget for upgrades. Or maybe the only single developer left the company in 2020. So whatever happens, we will all end up here, which leads us to the question, why migrate at all? Because sometimes, product owners ask me, if it works, why migrate? Dev just want some shiny stuff on their CVs.

I always answer, you know that I'm not a fanboy of any particular framework. For me, they're tools like hammers. But when I work, I want to use a good, reliable hammer, not the rusty one with missing parts. But migration is not only about developer experience. First of all, security. When the tech is outdated, the security patches stop and vulnerability reports start turning red. And enterprise projects are especially vulnerable to this because these apps often live much longer than originally planned. And no product owner ever said, okay, let's sacrifice security because we need more features at least I hope so.

Also tooling. So modern tooling, smaller bundles, white bills mean a faster app. And a faster app means a happy client. Libraries and integrations. If you have a third-party library in your project, which wasn't updated for five years, it seems even an author forgot about it and it doesn't compile or know it on an old 18. That's not working code. This is a time bomb. And my favorite point, tech debt has interest. And the longer you wait, the higher the cost of migration. That's why migration, it's not about hype. It's about the survival of your product.

How to migrate? We basically have two strategies of migration. First one is the big bang strategy. You rewrite the app from scratch or more often nowadays make a giant upgrade from an older version of the library to the latest one. For example, from React with classes to modern React with hooks and suspense. We also have the incremental strategy where you rewrite piece by piece while shipping features in between. And the one you choose should depend on reality, not preference. Because developers often treat migration strategy like a philosophical debate. But usually your project constraints make the decision for you anyway. If you remember just one slide from this presentation, let it be this one. How do we decide which migration strategy we should use? First question should be, can you stop delivering features for weeks or even months? If yes, you can try the big bang strategy. If no, you're already in the incremental approach.

Also big bang works better with the small or medium project. If you work on a really big project, big bang and freezing features would simply kill it. What does your team look like? If your team consists mostly of senior or mid-developers, big bang is possible. But if you have a lot of juniors in the team, it's better to go with the incremental strategy because they can learn meanwhile. Do you want a full UI redesign? It will be much easier with big bang because in an incremental strategy, two UIs need to coexist for a very long time. Documentation level. If your project is poorly documented with a lot of unknown edge cases, it's better to go with incremental because of the easier rollback strategy. Last but not least, security. If your app isn't security compliant, big bang may be the only option for you.

Let's talk a bit more about big bang strategy. In literature, you will sometimes read that big bang is risky. A last resort pattern. Even an anti-pattern. And it's totally true when we talk about 20 year old Java monolith. Better not to touch anything. But our front-end apps are usually relatively small and relatively modern. And sometimes it's just cheaper and faster to go with a big bang. Especially when we talk not about a full rewrite but an upgrade from older versions of modern libraries to their latest releases. I have to admit I like the big bang strategy. Yes, you need to freeze feature development for weeks or months. But then you end up with cleaner architecture, modern tooling, no legacy leftovers, easier life during security audits, and clean state for future updates.

And even on the diagram, it looks pretty simple. You do audit and plugging, then you freeze feature development. Next you do the migration work, then you have a phase of integration and testing, and then you go live with, of course, some rollback plan. Sounds good, right? And even every migration looks simple on the architecture diagrams. Well, reality isn't that romantic, which leads us to the first real-life story. It was a migration from Angular 7 to the modern Angular. And this app was already in production, but in maintenance mode. No one updated it for years. Suddenly, stakeholders decided to extend it significantly and add a lot of new features.

And we encouraged them to migrate the latest Angular first, mainly for security reasons. We were a team of four developers and the migration took us about four months, together with stabilization and bug fixing. I don't want to deep dive into the technical details of the migration because it will vary in your projects. What I want to tell you is how it actually looked so you can learn on my mistakes, not yours. So first of all, it's easy to underestimate. And I heard many times, Sylwia, why does it take so long? Because it looks easy, just upgrade Angular. And yes, that part was easy. But the ecosystem around this did. This is where the real pain starts. For example, the UI library that we used changed its syntax significantly, somewhere between version 12 and 13. Imagine the amount of templates that we had to be adjusted. Okay, we had coding agents now to help us, but you still have to spend a lot of time controlling the details.

Of course, we had some outdated libraries, incompatible with modern Angular. So we had to replace them somehow. Also, ngRx syntax changed meanwhile, so another hundred places had to be adjusted. And yes, we had a lot of end-to-end tests and 80% of them failed because of our UI library changes. So, well, additional work for the QA team. What's worth mentioning, we had one production hotfix during the migration. It wasn't a problem at all because of our clear branching strategy. But I can imagine a team which goes all-in, and then you will be doomed. In the end, the migration was a big success. We had two times faster builds, 20% smaller bundle, security reports finally went green. And what's more, the UI library in the modern version was much prettier and more accessible.

So even the most technology-resistant stakeholders were like, ah, migration, yes. Now I see it looks much better, which was quite funny for me. And of course, we had a clean state for future updates. And even the QA team, which at first hated us, now admits that updates should be done regularly, not once every seven years. Let's jump now to the incremental migration strategy, which in many projects is the only realistic option. Unlike the Big Bang approach, you don't need to freeze product development completely. The team can continue shipping features while the migration happens in the background.

And incremental usually means the strangler design pattern. There are also other incremental strategies, but strangler is the most common and elegant pattern. Moreover, used by many big companies. So battle tested. Okay, how does it work? As you see on my beautiful diagram, you have your legacy app. You build your new app on the side. You also build the reverse proxy. Then you rewrite screen by screen, route by route. And the reverse proxy decides which routes redirect to the legacy app and which to the new one.

Okay, time flies. You work hard, your new app becomes bigger. The legacy app starts shrinking. Ideally, every migrated route also removes a bit of technical depth and gives you some freedom to improve architecture tooling, etc. And eventually, hopefully, you can read of the legacy app and the reverse proxy and enjoy your new brand shiny app. Of course, in enterprise projects, temporary solutions sometimes survive slightly longer than expected. But even then, incremental migration is often far safer and more realistic than trying to rewrite everything at once.

Let's see a minimal example of a reverse proxy. As you see, you share the same back-end, same out, but not the front-end code. And honestly, this separation is very important, because once front-end applications start sharing too much code, migrations become much harder to control. And suddenly, the migration itself starts creating new technical depth. If you really need the front-end apps to communicate somehow, it's better to do it through custom DOM events. Avoid so-called temporary adapters, which of course last forever. And another important advantage of the strangler pattern, as you see on the example, you can or even should use feature flags for rollback.

And another important advantage of the strangler pattern, as you see on the example, you can or even should use feature flags for rollback. With a big bank migration, rollback can be stressful and complicated. But with strangler pattern, rollback is often just a feature flag switch. So if something goes wrong in production, you have an instant rollback to the legacy version.

Let's see the strangler pattern real-life story. This was an old app written in backbone. Big bank migration was theoretically possible, but the company was a startup, and one day, stakeholders came to us and said, hey team, we just saw the feature we don't have yet. You have three months to deliver it. Have fun. And I was like, yeah, funny, no way, I'm building it in backbone. I suggested migration with the strangler pattern and stakeholders agreed. They were smart guys and they knew it was the highest time to do this.

The team was me and two junior Java developers, who I swear heard the word TypeScript for the first time in their lives. Luckily, they learned fast. Well, they have no choice. First of all, I built a brand new Vue app on the sides and the reverse proxy. The first routes I migrated were the login screen for proof of concept, and of course, this shiny new feature the client already paid for. Then we migrated screen by screen, route by route, while shipping features in between. It took us more than a year, but eventually, we completely got rid of backbone.

With zero downtime, the client didn't even notice the migration happened. We had a five times faster build, a significantly smaller bundle, and a clean state for future updates. But the strangler pattern has also some drawbacks. First of all, time, much longer than during the big mac migration. It took us more than a year. There is also a risk of never ending migration. After a couple of months, people tend to forget that the migration is still happening, and you need to remind your product owner during every planning session, hey, we're in the middle of migration. We need to sacrifice some story points for it, and there is no way not to touch legacy code.

No way, and developers hate it. And I heard many times, Sylwia, why we are overcomplicating this. Now we need to know backbone and view. So whichever strategy you choose, you will always be a scapegoat. But don't worry, because after migration, you will probably become a company hero. Smooth migration is an art, and many things can go wrong. Here are the most common pitfalls. First of all, no plan. I often hear, let's migrate this up. Yes, let's migrate. This is not a plan. You need an audit first. How many screens do you have? How many end-to-end tests? What's the definition of done? There are just a few important questions.

Also, new framework, same architecture. Remember that migration doesn't always mean refactor, and if you blindly migrate spaghetti, you will end up with modern spaghetti. No roadmap plan. Always assume something will go wrong in production, and make sure you have a simple way back. Because during migration, you're changing not only business logic, but often also tooling, build process, routing, and integrations. And some small issues can be quickly very visible in production. Also, try not to dump six months of migration work on QA in a single sprint. They will hate you. And honestly, they will be right.

Because migration testing should happen continuously. Otherwise, the stabilization phase becomes painful for every involved. So always treat the migration as a product, not a side quest. It needs planning, priorities, communication, regular delivery, just like any other important business initiative. Because if migration becomes something we do on the side, eventually no one really owns it. And that's how migrations end up unfinished for years.

Okay, some final faults. Migration is like buying an old house. It's not your fault it's in ruins, but now it's your responsibility to renovate it. And you can take a couple of weeks off and fix everything at once. So that's a big bang strategy. You can also move in and renovate it room by room, like in a strangler pattern. The only bad decision is doing nothing. Then you have to migrate anyway, but probably during a production incident. Thank you.