Table of content
oadmap for migrating from the legacy Angular 1 framework to more up-to-date versions of Angular is your guiding star in the development world. With a step-by-step algorithm, you stay strategically focused on your tasks and make a rough prediction for the switch. In our new article, The Frontend Company team tells you, as promised, how to migrate AngularJS to Angular.
Please note that it is not a guide to action and not a tutorial for newbies. Here, our Angular development team shares their hands-on experience with the migration issue. Further, in this piece, we will describe the actions we took during the migration for some clients. While describing each step, our coders will elaborate on why a particular solution was used and what other choices would work for this process.
Insights from AVA.codes developers on how to migrate AngularJS to Angular
At the AVA.blog, we've started a new category dedicated to upgrading and migrating AngularJS-based web projects. Here you can already find articles on how to prepare for this process and what a good plan should look like before you start. We highly recommend reading these publications first before beginning today's in-depth story from The Frontend Company crew.
Some wisdom things about how to migrate AngularJS to Angular
- For each web app, the number of steps and tools for migration varies;
- there is no one-size-fits-all template for how to migrate to the latest platform;
- if you do not consider a roadmap for the switch in advance, the work is delayed, and the number of tasks increases;
- the Angular Team has not answered in the official documentation all the questions that coders may have;
- despite some development hurdles, the migration process is not so terrifying and has many pluses for many web projects;
- in some cases, building a hybrid application is better than making a web product from scratch;
- it is unnecessary to gradually switch from Angular 1 to the current version of Angular; you just need to work out a slightly improved plan for the upgrade.
Perhaps these are the main insights learned from dozens of similar projects. Since the rumors about AngularJS being dead soon, we've had many people regularly ask us to help their web apps migrate to Angular 2+.
Six key stages on how to migrate AngularJS to Angular
So, without further ado, let's go straight to how we usually work with migration and upgrade web apps.
Stage 1. Building a web application
It so happens that we more often have to migrate outdated AngularJS projects to later versions of the TypeScript-based framework. For this reason, our team mainly uses the Angular CLI for work. There's no secret here why this command-line interface (CLI) tool is preferred for Angular 8 and above for such web products.
First, this CLI has all the necessary commands that programmers will need at various stages of development built-in. You can see them on the official page, the link we gave in the paragraph above. Here you'll find solutions for linting, testing, and even a built-in webpack for loading modules. You don't need to use a third-party solution.
In 2017, coders were a little leery of how many tools and configuration files they would have to dig through to develop an application. Fortunately, the TS-based framework team made it easy for them by creating the CLI.
Second, since there are many things in the CLI, you can't do without builders. These functions will help you simply and quickly perform complex processes and figure out how to build a webpack for unit tests, run a server, etc. You should use the ng run command to start the builder. Necessary: the builder code is defined directly by the npm package, and for building or testing, you will have to use an application programming interface (API) called Architect.
And third, after the update in 2019, Architect is more stable than before. That's why our tech crew is actively using the Angular CLI to build web apps. Let's say, even more, you can make and customise your own builder using the official recommendations at angular.io. However, this is not the only way to migrate AngularJS to the TS-based platform.
Webpack's customization during web project creation
If the above benefits are not enough for you in the context of our how to migrate AngularJS to Angular story, then one more thing should be mentioned. Coders can customize webpack configuration if needed. Thanks to this, you can add your plugins and loaders, which is vital for migration.
Interesting: It is not always necessary to personalize the webpack. For some devs, the built-in features in Architect are fine. And those who don't need this API using the ng-eject command, don't bother with modification. However, starting from version 8 of the front-end framework, the ng-eject command was discontinued, so coders were forced to use other solutions. They are more convenient than ng-eject in The Frontend Company team's opinion.
The following is required to configure the webpack configuration:
The task of the first tool we require is to notify the coder of the build. If everything is done correctly, there will be no notification. The second tool sends native cross-platform notifications to NodeJS and the user. And the PostCSS loader will help with styling conversions the way we want.
More information and documentation about webpack customization can be found on the GitHub website.
Alternative solutions on how to migrate AngularJS to Angular
Of course, things don't always go smoothly at work, and there have been situations where using the Angular CLI was not possible. For example, a hybrid web application supported elements and features outside of Angular. When upgrading to version 8+, we had to give up the handy CLI (builders have been officially supported only since May 2019); instead, we switched to Webpack or Gulp.
What do we do with these tools?
Webpack is an easy-to-use module builder that can analyse the modules of your web project and create dependencies. It helps us put modules together in the right way, reducing the runtime of some development processes.
Here, we feel it would be better not to mislead you and tell you how to use this tool step by step. The main reason for such a decision is that even within our company, we use different versions of Webpack. Technical nuances and algorithm of actions for this builder are better to read in the official documentation.
To be honest, we don't use Gulp that often. But in the concept of our conversation on how to migrate AngularJS to Angular, it is relevant to talk about this tool. In general, the task of Gulp is to automate routine development tasks.
Interesting: Gulp is actually a «child product» of the JS task runner called Grunt.
Stage 2. Configuring template loading for smooth migration
Here we will not go into as much detail as we did in the first stage. First and foremost, we would have to add whole pieces of source code here. That's not a suitable format for our experience description on how to migrate AngularJS to Angular. Instead, we're sharing the basic stories of what we used and why. We'll also uncover a couple of secrets that we could have really benefited from in our time.
In hybrid web projects, you need to support template loading for two front-end frameworks at once. Since both technologies use HTML templates, you don't need to upload files separately most of the time. However, we want to warn you up front that this is a must for some web products and services.
If you're lucky, you can use templates, and everything will work fine. Extremely rare, but we had encountered such projects when loading patterns went according to the canon in theory and practice.
What it would look like under ideal conditions and in a perfect migration process?
When working with Webpack, the standard Template loader, which many development teams utilize, works well. Its advantage is that it reduces the initial loading time of templates and has flexible settings.
Theoretically, coders can even configure it to work with different loaders. It takes a little longer to do that. Especially if you want to use slightly later Angular code. We had to dig quite a bit into the documentation and learn every single configuration we could.
You can use an AngularJS template loader, but you can hunt for something up to date or more convenient. Quite often, programmers in the process refer to angularjs-template-loader, which in turn is a port of angular2-template-loader. We will also talk more about tools in The Frontend Company blog.
Interesting: For Webpack and the above-suggested loader, you can set up a wide variety of template-loading chains. Usually, we only need to add a couple of rules to make everything work perfectly. Or nearly perfectly.
And here we are forced to say a spoonful of tar, spoiling the perfect switching plan on how to migrate AngularJS to Angular.
In fact, The Frontend Company team programmed everything themselves. We took existing templates as a basis during the development process and used them to create templates in Angular. Obviously, the manually built templates referenced the already available templates. That is our biggest secret of success in the context of how to migrate AngularJS to Angular. Such an approach takes more time, but we are 100% sure that every template works appropriately.
Autogenerators will indeed save migration time and build templates. It will not always be human-readable, and not all coders can figure out how to use them. Before you start utilizing the recommendations described above, you should consider whether this is relevant for your particular web project.
Also, you probably need someone on your team who will be experienced enough to adapt the templates to suitable parameters in case of need. Don't think we're contradicting ourselves. It's just that for small web apps, it can work. It's better to make sure and write templates for Angular yourself for niche and complex products.
Note: Still, most of our crew is biased towards the fact that the generated templates will complicate further development of the project and its support. We think it is worth mentioning in the story how to migrate AngularJS to Angular smoothly.
Stage 3. Setting up the S2S compiler (for the lucky ones)
The next part of our piece will probably not be all-purpose, either. We want to warn you that our recommendations will work under optimal circumstances. Here, The Frontend Company team wants to discuss how to migrate AngularJS to Angular, thanks to the S2S compiler (source-to-source compiler).
We will use the TypeScript transcompiler to convert one programming language to another. Only two functions will need to be enabled beforehand:
You do this step to make the decorators work correctly. If you don't prepare the S2S compiler to handle the TypeScript-based framework, the migration mechanism you've fine-tuned up to this point will not start.
For us, everything is excellent about the TS transcompiler: our specialists can create the necessary solutions and write code on their own, without thinking about how to bypass the next crutch of development. The drawback is that you spend more time and effort on the process.
From our experience, we can say that the out-of-the-box solution didn't always do what we expected in some projects. In such a case, we had to look for workarounds for blockers frantically; it took a lot of time, too.
If you add it up, we spent plus or minus as much effort as we did for creating our custom solution. The compiler control in our hands is often more predictable. That is why we turn to it for help 7 out of 10 times. On top of that, there's support for the AoT compiler, so skyrocket rendering in the browser.
What else can we use? We won't recommend anything niche or little-known here. For a similar task, Babel is quite good.
Stage 4. Customizing polyfills for browsers
At this level, our Angular development team usually realizes that half of the work is behind us, and we can see the finish line somewhere in the distance. We've already shared the highlights of how to migrate AngularJS to Angular. After setting up templates and selecting transcompilers, it's time to start setting up browsers.
You shouldn't have any difficulty; just fine-tune the polyfills according to the recommendations. The advantage is that the official Angular team has shared a guide that helps you organize everything perfectly, or at least okay.
Because Angular's work is built around the latest standards for web platforms, the challenge here is that the number of browsers and their versions is growing. Before, there were 2-3 popular browsers, but now the same person can use different browsers on all devices. Rather than confining browser support manually for each version, it is easier to customize polyfills.
One should note here that it is not always the standard browser that supports the features that your web project and your users need. It is where polyfills come in, where you can enable support for one option or another. By doing so, you can significantly improve your user experience components.
Note: Different web and mobile browsers have specific polyfill configurations. You should first check the official documentation and only then get down to business. Also, keep in mind that you are bound to run into missing polyfills for outdated browsers. Then you will have to do some brainstorming.
By the way, The Frontend Company team has one case in point about outdated browsers. The situation did not happen to our coders; therefore, we will tell the story without worthless details. One day, our colleagues faced the problem that Internet Explorer (IE) 11 did not support ES-2015. As you can imagine, later features weren't available either. It was clearly the time when they couldn't do without polyfills.
The application developed by our colleagues did not show any errors in other browsers. However, as soon as IE11 was launched, chaos began. At that time, the programmers could not ignore this browser version, even though it was very outdated compared to other solutions. The team had to dig out the polyfills.ts file and import all the necessary polyfills into it. The devs also included custom properties CSS as an add-on. After that, everything worked properly.
Interesting: There is an option of differential loading in version 8 of the TS-based framework. It is a tricky feature for older versions of browsers. For one, if you used ng serve and updated the web app through the command-line interface, ES-2015 runs by default. That is, there are problems when IE11 is started.
For another, the other older versions of browsers do not support differential loading either, so you will have to trouble yourself. We are not certain how much of this note is relevant to you. But we find it curious, especially in the context of our experience on how to migrate AngularJS to Angular.
Stage 5. Setting up bootstrap
Our crew most often acts in the traditional way for many projects during this process. We bootstrap each part of the web app. Here we stick to the official recommendations; we load Angular code first and then AngularJS source code. It will be easier to use UpgradeModule for our end goals with this sequence. Sadly, for hybrid web projects, we have to do bootstrapping manually.
We can use the root module to bootstrap AngularJS code. It is also suitable for this task. You can go to the official guide for details.
Note: For everything to work like clockwork, you'll have to switch the AngularJS code to use angular.bootstrap by hand at the preparation stage. The important thing is to do so before the development team starts using the hybrid web project. Otherwise, you can't avoid needless complexities and roadblocks in the other stages of the migration.
Once the programmers are done preparing and enabling manual bootstrap for the AngularJS-based project part, we can move on. The Frontend Company team usually creates app.module.ts, and then using the NgModule class and the import option, we export declarables. The latter will be available to templates directly in the NgModule.
Ba dum tss! The created module helps import the obligatory module for the browser app and the UpgradeModule we talked about at the beginning of this block. After that, it's crucial not to forget to utilize DoBootstrap to load the AngularJS part of the project. This method is along the same lines as angular.bootstrap.
That's not the end of the story on how to migrate AngularJS to Angular. After coders have done all the described recommendations for bootstrap, they will finally have to bootstrap AppModule. The Angular framework team itself recommends doing this via the platformBrowserDynamic.bootstrapModule method.
Stage 6. Adjusting routing
In the previous blog post, «AngularJS to Angular migration plan. Pros tips on development», we already told you about the mechanism we use for this aim. Our experts are most involved with the ngUpgrade library.
The easiest option in this situation would be to define routes for both JS-based and TS-based frameworks. There's nothing out of the ordinary here; we just proceed as usual. Then we create a particular class and name it, primarily according to the project. It's simpler in the future to understand what was done in the routing process and for what purpose.
Besides the new class for linking the two frameworks, we write the same class inside the main component in the hybrid app. After that, our team updates the root component and includes the Angular router.
That's the end of our experience on how to migrate AngularJS to Angular. Then, depending on the specifics and industry, The Frontend Company team works on additional steps. Above, we share with you six basic steps, which are regularly repeated during the migration of different web projects. If you need migration or professional advice, please get in touch with our Managing Partner Viktoria for help.