Migrating Angular: From v16 to v17

📸 Image: Credits and thanks to Ravi for the image above! Taken from Unsplash.com.

⚠️ Important Disclaimers

☑️ For security reasons, some details have been intentionally left out.

☑️ This is not a step-by-step guide or a document to follow for updating an Angular app.

☑️ This article provides a general overview, reflections, and storytelling on how the upgrade was achieved within the given context.

Intro

It's no secret that YouTube, Udemy, and Coursera tutorials are light-years away from real-world corporate projects. You might learn the basics—React Hooks, Angular bindings, or SCSS nested classes with their quirks—but when it comes to actual production code, things can get pretty intimidating.

Now, add the challenge of working with legacy code, written by developers who left the project long ago. And let’s not even mention the missing documentation or the total lack of guides that could give you a clue about what a mysterious block of code actually does or where key resources are buried.

And if that’s not enough, imagine being tasked with upgrading the entire front-end engine to a newer version—it's like going to war in the dark.

Well, I found myself in exactly that situation—and somehow, I made it through!

Of course, I didn’t do it alone. I had help, especially from a close dev colleague I work with every day. So all credits are shared and kudos to my trustworthy friend.

Additional

It's funny how life’s coincidences happen. A couple of weeks after completing the upgrade, I came across a really interesting article about a similar upgrade done by Airbnb. How cool is it to find a write-up that describes the exact same work I had just accomplished!

Feeling proud and excited, I shared the post on my LinkedIn profile, adding some personal thoughts on the process.

The article itself is the following: "How Airbnb Smoothly Upgrades React" by Andre Wiggins.

Story

Some tech details to take into account: (1) This upgrade was from Angular v16 to v17, and (2) by the time of the upgrade v19 Angular was not released yet.

The assigned task was simple: upgrade Angular to stay within LTS and avoid falling behind on releases, while also protecting the project from potential security breaches.

Summary

It was a success! The upgrade worked as expected, with minimal issues from breaking changes.

Full Context

🖥️ Tech Context

As far as I was told, the project originally started with Angular v13 and remained on that version for approximately a year and a half. Then, about six months after I joined the project, the first upgrade was executed—from v13 to v16—by a fellow developer who was in charge of the main UI components.

When we were assigned the second upgrade, our first task was to evaluate whether to upgrade to v17 or go all the way to v18. We had to analyze the time effort, potential breaking changes, and which option would be the most practical.

Of course, the answer was pretty straightforward:
✔️ Move to the next version and make it work without breaking anything.
✔️ Ensure that clients wouldn’t even notice the upgrade happened.

💻 Tech Context

The UI of the project is split into two main modules:

🏢 -> The main app UI.

🏛️ -> A built-in custom component library with a playground to showcase all components, which feeds into the main app.

Since both modules are separate Angular projects, this meant we had to perform two separate upgrades to ensure compatibility. The full upgrades on both cases took about a full sprint, approximately two weeks.

The steps we took to make the upgrades were:

1️⃣ Created a decision document

• We analyzed the pros and cons of upgrading to v17 vs. v18.
• Once the decision was made, we expanded this document into a guide to define the best strategy for the upgrade.

2️⃣ Conducted thorough research

• We reviewed Angular’s official documentation on upgrading.
• This helped us identify the required changes to comply with the new rules introduced in v17.

3️⃣ Presented the upgrade strategy

• We compiled an approximate estimate of time, development effort, and potential challenges. Alongside with the breaking changes.
• We also took into consideration possible upgrades of third-party libraries we also use in the project that must be upgraded in order to work as well.

4️⃣ Do the upgrade

• We executed the upgrade on both projects and began testing the entire app to ensure everything worked correctly.
• We deployed it to a test environment multiple times to verify all changes, carefully inspecting the ng-version on each deployment.

After multiple deployments and thorough testing, the upgrade was a success both locally and in an isolated test environment—though not yet in the DEV or MAIN environments. This was our primary objective before moving forward.

The Day After

Once we successfully deployed to our development environment, we initially thought the entire operation was a complete success. However, we soon noticed that the local Angular server was experiencing serious performance issues.

⚠️ The problem?

• It was consuming a huge amount of memory, causing the app to frequently crash and even overheat the computer.
• It seemed that the new Angular update had issues with the builder and hot reload.

✅ The solution?
We switched to the new esbuild-based builder with Vite:

👉 @angular-devkit/build-angular:browser-esbuild

This not only fixed the performance issues but also made the entire project significantly faster.

Although this builder was already available from v16, it had not been applied. However, for v17, it became essential in our case.

Other challenges

In the weeks following the upgrade, the most common issue we encountered was with the UI framework we use for our components.

• Some functions were deprecated.
• Some component names were changed.
• Most unexpectedly, some automated functions—such as dropdowns, panels and checkboxes, among others—became manual.

Fortunately, styles were largely unaffected, and the Angular app itself functioned correctly, with most flows appearing stable. However, the UI components where these changes were applied were significantly impacted.

Nothing that sitting down and carefully debugging couldn't fix!

Conclusions

For my first time participating in an Angular upgrade process, I definitely felt up to the challenge. This wasn’t my first time handling upgrades—as you’ll find in later posts on my blog—I had previously upgraded Next.js a few times, as well as a create-react-app project. However, those were small and simple projects compared to this one.

The bigger the project, the harder it is to keep everything up to date—even more so when working with a team of over 50 people, including developers, BAs, SMs, POs, QAs, stakeholders, and more.

Lessons Learned from This Experience

📘 Angular updates and releases move fast.

• This might not be news to some, as rapid updates are common in certain software. If this is the case for your project, prepare accordingly by allocating time and resources to make upgrades a regular cycle.

📘 You don’t have to upgrade with every release.

• It’s not always necessary to update immediately with every new version, but try not to fall too far behind either.

📘 Teamwork is essential!

• Upgrades like these can be done by a solo developer, but it's best to work with two or three teammates. Constant feedback, double-checks, reviews, and testing are key to success.

📘 The more complex the business, the more complex the project—and the harder the updates.

• Larger projects with intricate business logic make upgrades even more challenging.

📘 Confidence is key—trust yourself!

• Sometimes, things aren’t as hard as they seem. Learn as much as you can, trust your abilities, and research properly. Every goal can be achieved successfully with the right attitude.

📘 Patience is crucial.

• Be transparent about the process.
• Share and show real progress to interested parties.
• Communicate effectively.
• Create a strategy and stick to it—but be flexible enough to adapt to unexpected circumstances.

Recommendations

Here are some recommendations I would give to others—and follow myself—when working on projects and upgrading them to newer versions:

✅ Keep your project updated constantly.

• This includes keeping third-party libraries up to date as well. Don’t wait too long to make the jump!

✅ Be cautious with the latest versions.

• New releases may be buggy, fragile, or introduce breaking changes, so if necessary, stay close to the latest stable version instead of always jumping to the absolute latest one.

✅ When upgrading across multiple versions (e.g., v16 to v18), set checkpoints.

• Find a stable intermediate version, deploy it, and then proceed to the next upgrade. For example, if v17 is stable, deliver that first before moving to v18.

✅ Avoid tech debt at all costs.

• It’s better to push small but high-quality code that follows best practices rather than shipping multiple features with inconsistent logic.

✅ If taking on technical debt, document it properly.

• Be aware of the potential long-term cost, and make sure the team knows the risks. It can make the next update to break those code!

✅ Follow code conventions strictly.

• Once coding guidelines are set, stick to them. They exist for a reason!

✅ Don’t reinvent the wheel!

• Understand the framework you’re using and follow its best practices, recommendations, and styling guidelines.
  • Each new release builds upon previous versions, so sticking to the framework's best practices ensures a smoother upgrade process.

✅ Don’t rush!

• Even if 90% of the app seems to work, don’t assume it’s safe until you verify the remaining 10%. Just because it works in most places doesn’t mean it works everywhere.

✅ Test everything properly, especially if the product is live.

• Thorough testing is critical when the product is already in production.

✅ Be wise when choosing the stack at the first stage of the project.

• The key to every successful project is choosing the right tools at the earliest stage of architectural design.
  • Don't just follow the crowd: Avoid picking tools just because they are popular—what works for others may not be the best fit for your project.
  • Analyze the project with a medium- and long-term perspective: Find compatible tools that integrate well with each other and will remain relevant as the project evolves.
  • Look for proven success cases: Choose technologies with a track record of delivering value and measurable benefits.
  • Consider how updates will impact the project: Keeping up with the latest releases is crucial, but it’s hard to predict the direction a framework will take.
    • Choose tools that offer:
      ✔️ Strong support.
      ✔️ Robust security.
      ✔️ A history of reliable updates.

✅ Create a strategy, build a plan.

• Have a strategy and stick to it—but be flexible enough to adapt to unexpected circumstances.

✅ Be prepared to backtrack if needed or requested.

• It may not be ideal, but it's a situation that can happen.

Final Notes

On a personal note, it feels incredibly rewarding to be part of this kind of project. The knowledge gained and the experience acquired not only help me grow as a developer but also as a person and a professional.

I feel grateful to be part of work like this—something I have always aspired to be involved in.

Cheers,
Randy MS

🍀