Five Things I Wish I Knew
When I first moved to Oregon, I had zero experience with hiking or backpacking. As a lifelong Southerner, I really wanted to spend time outside camping and exploring, but I had no clue where to start. I was totally overwhelmed, especially since native Oregonians made it look so effortless. How do I pick a destination? What do I need to bring? What skills do I need? Eventually, I learned there’s a rubric – a set of questions and criteria – I can use to plan my trips and what gear I’ll need. I’ve used that rubric to build a system and improve it over time with experience.
My first experiences with ngUpgrade were the same way. I was faced with a big upgrade project and was totally overwhelmed. I pored over the documentation and was left with more questions than when I started. How do I use a bundler? How do I get started with TypeScript? What exactly do I need to do to get ngUpgrade working? And, most importantly, how the heck am I supposed to do all of this while still doing all of my normal work, like bug fixes and feature development!? I dug deeper, devouring every book, workshop, and video course I could while working through the process. Eventually, I channeled all of that blood, sweat, and tears into building the course on ngUpgrade I wish had existed when I started.
In building that course, I discovered there are some patterns that come together to form a rubric for evaluating your upgrade path. To that end, here are five things I wish I knew before I started on my ngUpgrade.
1. Using ngUpgrade is less work than rewriting to a different framework.
I get asked this question all the time. The ngUpgrade library (found in `@angular/upgrade/static`) allows AngularJS and Angular to run side-by-side while you incrementally migrate your application. ngUpgrade provides an API that lets you upgrade and downgrade your components and services, which means making them available to both frameworks. There’s no equivalent to ngUpgrade for other frameworks. Is migrating a big application a walk in the park? No, it’s still technical debt that has to be addressed. But you’re not going it alone, and you’re not burning down your old code base and rewriting from scratch.
2. Your starting point matters.
One of the great things about AngularJS was its flexibility. You could use AngularJS inside of a .NET MVC project for data binding, or on its own to build complex SPAs, or all kinds of things in between. Unfortunately, this also means there were lots of different approaches to styling and architecting AngularJS apps, especially before John Papa’s style guide came along. Each different application style becomes a different starting point for upgrading to Angular, and that starting point really matters in how you design your upgrade. Here are some good questions for your team to ask as you plan:
- How big is your application?
- How is it structured (modules, flat files, script tags)?
- How far back is it? (What version of AngularJS? Is it using $scope, controllers, etc?)
- How big is your team?
- What’s your development cycle look like?
- How much feature work or production support do you have to do?
Start thinking through the architecture of your application and how you need to tackle this upgrade. There’s good news, though: Angular has a much more established set of best practices for code structure, tooling, and application architecture. While ngUpgrade has many starting points for this, it has one end result. You don’t have to spend time guessing about how to organize your files or how to set up applications. The official docs now have a style guide baked right in.
3. Once you understand the fundamentals, you can customize your plan.
ngUpgrade breaks into two phases: Preparing Your Code and Migrating Your Code. Preparing your code to upgrade involves what I call the four building blocks: your files, your dependencies, your architecture, and your build process. You’ll mix and match these building blocks based on your application’s needs. For example, if you’ve got an old type-based folder structure (folders like “controllers” or “services”) and lots of uses of `$scope`, you’ll have different work than someone already using ES6, TypeScript, and AngularJS components. You don’t necessarily need to get your code to perfect AngularJS before you start migrating, but you’ll need to be aware of the impact of these different building blocks. Migrating consists of bootstrapping both frameworks, setting up your production build to use AOT compilation, and then methodically moving pieces of your application to Angular. Once you know your app, the fundamentals of upgrading, and your desired endpoint, you’re able to customize your plan to your needs. This plan will let you know the size, scope, and duration of your upgrade much better than simply digging in and hoping for the best.
4. Invest in your build setup.
Getting the build setup right for your upgrade is one of the most difficult and time consuming steps of the process, but will pay off exponentially when done right. You have two choices: the Angular CLI or a custom Webpack setup. Either of these will require you to replace your script tags or task runners (like Gulp or Grunt) and move your application to ES6 modules and TypeScript. Using the CLI is ideal, but is often difficult for big AngularJS apps that are not ready to move to such an opinionated folder structure and build process. In that case, you’ll need to set up a Webpack build that can be used in both development and production. You can then switch to the CLI later, once your app architecture more closely resembles the style of a CLI project. Whichever you choose, allow yourself to take the time to get it right. You’ll want your legacy AngularJS code to run alongside of your new Angular code, and you’ll need to deploy it to production without breaking anything and without bloating your bundle size. It may feel like a lot of work on infrastructure, but it’ll pay off in the long run as you’re able to simultaneously maintain and migrate your legacy AngularJS code while developing new features in Angular.
5. Slow and steady wins the race.
Take the time you need to do this upgrade right. AngularJS is going to be in a Long Term Stable period from July 1, 2018 until June 30, 2021. None of the instances of AngularJS in package repositories or CDNs will disappear. So, plan your approach and execute it methodically. You can take it route-by-route, or you can take a more top-down approach. How you tackle this depends on how much other non-upgrade work you need to do. I like to get my hybrid set-up and build system working, then draw a line in the sand for new feature development. All new features from that point get written in Angular. As for the legacy AngularJS code, it helps to use a “Midas touch” approach. Any time you touch a piece of legacy code while adding something new, turn it into Angular. One other tip: don’t stress out about immediately having to implement new patterns like reactive programming or advanced state management like NgRx. If you’re writing a new feature, sure, feel free to experiment and learn. For the migration, though, take advantage of “bridge tools” like template-driven forms and the `toPromise` method in RxJS. It’s okay to translate AngularJS ways of doing things into Angular for the time being, and then worry about moving to Angular patterns as you’re able. Or, as a friend of mine once put it, “First migrate, then get fancy.”
Where to Go From Here
Moving a big application from AngularJS to Angular can feel completely overwhelming, especially if you don’t know where to start. If you’ll invest the time to create the right migration plan, you can save your team hundreds of hours and tens of thousands of dollars. Knowing how to tackle things like your architecture, your build process, and the migration itself will guide you as you spend the time refactoring and learning the new Angular patterns. If any of this sounds completely daunting, or if you have no idea what I’m talking about, I’ve got your back. I’ve got 200+ videos, sample code, quiz questions, and more waiting for you in my comprehensive video course Upgrading AngularJS. Head on over and sign up for our email list to get yourself a free Upgrade Roadmap Checklist so you don’t lose track of your upgrade prep. And, while you’re there, check out our full demo. See you there!
