At Lob, we recently migrated our user dashboard from AngularJS to Vue. While this is a large technical undertaking, the more interesting and valuable lessons didn’t involve code at all. So this is not a story about the differences between two frameworks, but about how to approach large business-critical projects in a way that minimizes downtime and user inconvenience.
Lob originally built our user dashboard with AngularJS, which at the time was a revolutionary frontend framework—in the early 2010s, jQuery was the king of Javascript tools. AngularJS brought more structure and saved many developers from the spaghetti code that accompanied many jQuery built frontends.
Fast-forward to October 2020. Google announces that AngularJS will no longer be maintained after December 31st, 2021. On top of an already stressful year, this was news no one at Lob wanted to hear.
“I understood that we needed to move away from Angular, it was going to be end-of-lifed in December” said Shampa Roy, product manager for the Dashboard and Growth team. “So, we had to pick something and I had heard feedback from the team that no one liked working in AngularJS.”
Choosing the right tool
Choosing the right tool is very important and a decision that has a cascade effect on everything else. For Lob the choice was between React, Vue, and modern Angular. But what is even more important than the technical aspects are the externalities around your project. For Lob, those externalities were based around developer on-boarding, hiring, and enforcing good practices.
“React is not super opinionated, it has a much larger community than Vue does, and it's a lot easier to hire for, and has a ton of options if you are looking for premade components,” said Mercedes Bernard, Principal Engineer. “But some of the cons are that you can truly do whatever you want in React. You can do a lot of anti-patterns and it can be hard to find code samples to match up with what you are doing because everyone has a different style.”
Beth Qiang, Senior Software Engineer, agrees. “The big concern about switching to React is that it is very easy to write bad code,” Qiang said laughing. “Vue is opinionated enough to mostly enforce good code, but not as opinionated as Angular which is very strict.”
Both also agree that the relative ease of onboarding makes Vue a very good choice. “It's relatively easy for someone to jump into a Vue project and kind of figure out what’s going on. And their docs are very good,” Qiang said.
Navigating legacy code
Imagine having to rebuild a project in a new library, but there are no written requirements on how the existing project should work. The only thing you have to go off of is the code—almost a decade of cruft, loose ends, experiments, and deprecated functionality—to weed through.
This presented a big challenge for the engineering team, many of which were new to Lob and learning the business rules themselves.
“No one on the team knew why any decisions were made,” Qiang said. “The only things we had to go off of were very vague Jira tickets or PRs that said ‘fixed this’ but didn’t say why that thing needed fixing in the first place.”
“It was archeology,” Bernard said. “The old dashboard had a ton of undocumented features that no one knew it supported. Then it was a conversation and questions about how often does this [feature] get used? Is this something that we used to support and it is now deprecated?”
A key takeaway from this situation is be kind to your future self and others by documenting the code. Create concise yet descriptive Jira tickets, pull requests and commit messages. Ideally, your future self—or someone else—could piece together why the changes were made and maybe link back to the team/unit that requested the change, e.g. “Accounting requested we add sales tax to customers with an in-state billing address.”
Digging through the code took time and impacted our original deadline. Managers should include this excavation work in any project estimates. Moving from one framework to another should bake in time for getting familiar with the existing framework if the developers don’t have experience in both.
Refactor and enhance
During a refactor or port of a codebase it makes sense to extend the code. For Lob, a long neglected task was improving accessibility in the dashboard. Any desired extension requires planning in order to get a team that has the needed experience. Qiang and Bernard both have strong experience implementing and testing accessibility features in projects.
“Lob values curated experiences, and seeing that our users are very diverse, this was something that doesn’t hurt the existing users,” Roy said. “This can only help the people who need it. The engineering team did a good job focusing on accessibility and I learned a lot from them during the project.”
If you want to learn more about the technical details, Beth Qiang is speaking at Axe-Con this year about accessibility in component libraries. Since Vue3 is still fairly new, it lacks a library of pre-made accessible components, but the good folks on Lob’s dashboard team are sharing their Storybook and Github repo, so you can integrate them into your projects.
Managing the launch
More than sixty-five pages and 35 unique components later, the new dashboard was ready to go. When launching a large project it’s important to have a rollback strategy and phased approach. It also makes sense to have tracking software for developers to accurately recreate bugs when they occur. If your project is front-end focused, analytic tools like Hotjar or Fullstory may be appropriate. On the backend, monitoring tools like DataDog or LogRocket can be helpful.
“One of the drawbacks of doing a full rebuild was simultaneously running two dashboards on different domains and completely different codebases,” said Bernard. “The question became how do we serve one set of customers with one codebase and another set of customers with another codebase?”
Lob makes use of LaunchDarkly, a tool—that through feature flags—allows you to route customers to different experiences. Working in coordination with customer-facing teams, the dashboard team was able to strategically select users to use the new dashboard.
“We wanted to roll out to self-service customers first in small batches. As we gained confidence with each of the [pricing] tiers, then we worked with the biggest accounts,” Roy said.
“It was as easy as putting an account ID into an input box in LaunchDarkly, in order to switch the customer between v1 and v2” said Qiang.
The other difficulty was overriding the usual authentication method so that customers could enter on dashboard.lob.com, then be redirected to either the old AngularJS dashboard or the newer Vue dashboard. It’s important, especially on the frontend, to honor old URLs because users may have them bookmarked. With the redirects in place, developers diagnosed any issues that arose for a customer. They would know which version of the dashboard the account was viewing, making it easier to debug issues—was it something that only showed up in the newer version? Was it something that was broken in the old version that carried over?
Putting it all together
The AngularJS dashboard has been officially retired as of the middle of February; in the past 30 days, over 1,800 users have experienced the new Vue version. A large project rollout with minimal downtime and user inconvenience is the best possible outcome, but it takes deliberate planning upfront to make it possible: select an optimal framework, build in time to unravel existing code (and make the next project easier by documenting the new), take the opportunity to enhance, and finally, have a clear rollout—and rollback—strategy. Hopefully, this will help spark discussion around the next large project you and your team are about to tackle.