Mutate a code like a boss — with Angular schematics

This article tells you how we are trying to do work with schematics easily and how to work with AST outside schematics in any project.

Mutate a code like a boss — with Angular schematics

For fulfilling using Angular CLI, developers have to know about Angular schematics. ng add, ng update and ng generate use schematics to add, update and configure libraries and generate code for applications. At runtime, you get access to a virtual file system and can mutate source code as you need. “But for code mutation, I have to work with AST. It is so hard.” — say you. And you are right!

This article tells you how we are trying to do work with schematics easily and how to work with AST outside schematics in any project.

What is a schematic?

Technically, the schematic is a function with two arguments:

  1. Schematic configuration
  2. Context. Used it for logging. Contains some utils.

The schematic function returns type Rule. Let’s look at this type:

Rule can be synchronous or asynchronous. As a bonus, Rule can return Observable.

The last unknown type here is Tree. Tree is an abstraction for working with the virtual file system. Any changes in the virtual file system apply to the real file system.

Each Angular CLI command working with schematics has its configuration, but in the end, it is just calling the above function.

Why do we use schematics?

We use schematics a lot, and we have reasons:

  1. Migrations. We use migrations when releasing libraries with breaking changes. Migrations help developers make updates softer. Angular CLI uses migrations with the ng update command. We even contributed to RenovateBot to run migrations automatically when the dependencies are updated.
  2. Library configuration when added to a project. Schematics allow preparation immediately for the project for using the library (add imports to the module, inject default configs, change build process, etc.).
  3. Code generation (easy and quick creation of component, directive, library, service, etc). For example, schematics can create a lazy route with all the needed configurations.

I can write a large list of cases for each item, but let’s leave it to your imagination.

As a result, we can say that writing schematics is a good time saver for users, but…

We have a problem

We had a simple task to add the module import to AppModule. After development, we realized that we had spent much more time than expected.

What was the problem? We decided to use AST for code mutation. But AST is not a simple thing for developers who are just working with Angular services and components.

For example, the Angular team uses the typescript API for migrations. How often do you face using typescript programmatically? How often do you operate the nodes from the TS compiler to add a couple of properties to the object?

Below is a simple example of a function that adds data to the module metadata (original code). CAUTION: the code is given as an example. I do not advise you to strain yourself and understand what is happening in it!

Looks difficult.

Complexity is the main reason for creating a high-level library that allows you to mutate your code easier!


It has ts-morph under the hood and allows you to manipulate with safe TypeScript AST.

ng-morph is a set of utilities that will allow you to write schematics much easier and faster. Let’s look at a few examples of using it.

Example #1

Add import of the SomeModule module to the root module of the application.


Let’s look at the solution line by line:

  1. Create the ng-morph project and set it active. It is important because all of the functions work in the context of the active project. Project is a class with access to a file system, the TS compiler, etc.
  2. Find the main application module by entry point.
  3. Add a new import to the main module.
  4. Add a new import to the file of the main module.
  5. Save the project.

Now compare this solution with the function above from the Angular sources. If you use ng-morph, you probably won’t have to write something like this.

Example #2

We should rewrite enum names to uppercase.


Common questions: “Why should we use schematics for this? The schematics are too complex to rename enums”.

You are right. But let’s look at ng-morph power!

  1. Create a project. There is an important moment. The script is not wrapped by a schematic function, and Tree is created manually with NgMorphTree.
  2. Find all enums.
  3. Rename all enums.

This example shows us that ng-morph can work outside of schematics! And yes, we use ng-morph in non-Angular projects!

What else can ng-morph do?

  • Create
  • Find
  • Edit
  • Remove

Almost every entity in TS has its own set of functions (get*, edit*, add*, remove*). For example getClass, removeConstrucor, addDecorator. We started to develop utility functions for working with Angular-specific cases:

  1. getBootstrapFn is a function that returns CallExpression
  2. getMainModule is a function that returns the main module declaration.
  3. Many utility functions for changing the metadata of Angular entities: addDeclarationToNgModule, addProviderToDirective, etc.

ng-morph can work with json. For example, you can add dependencies in package.json:

If you need lower-level work, you can always work with the ts-morph API and fall even lower into the typescript API.


There is no roadmap at this time. We quickly implemented what we were missing and decided to show it to the community. We want to develop the instrument further.

Nevertheless, there is still a list of essential features:

  1. High-level work with templates
  2. High-level work with styles
  3. Increasing tooling for working with Angular entities

And we’ll be glad if the Angular community can help us do this!

GitHub - Tinkoff/ng-morph: Code mutations in schematics were never easier than now.
Code mutations in schematics were never easier than now. npm i --save-dev ng-morph You also need @angular-devkit/core…
Documentation and examples

Already using ng-morph

Our friendliest and best component library for Angular known to me

GitHub - Tinkoff/taiga-ui: Angular UI Kit and components library for awesome people
Taiga UI is fully-treeshakable Angular UI Kit consisting of multiple base libraries and several add-ons. It is based on…