Forem: Roman Sedov

ng-morph is the best way to do big changes in your Angular project

Roman Sedov — Thu, 06 Apr 2023 05:38:04 +0000

I have been working on big Angular projects for years and every project follows the same path: it starts with brand new tools and approaches that lay its development style for the future. Approaches and tools change with time and the project has tech debt around migrating to new package versions, replacing a deprecated approach with the new one, etc.

Sure, not every team can develop and support all the business needs and find the time to sync their code base with pioneering development methods. But what if I show you a tool with which you can transform the whole project just with several lines of codes?

What is ng-morph

ng-morph is a large set of tools for both global code base updates in your project and speeding up your work on Angular schematics. It has ts-morph under the hood and allows you to manipulate with TypeScript AST safely.

You do not need to know how TypeScript works under the hood to transform your project. You can use simple ready functions for manipulating TS and NG entities. Moreover ng-morph adds several benefits in the process:

You make changes in virtual file structure. So, you can check the new structure first, fix all the bugs and inconsistencies before saving changes in the real project structure. It is much faster than migrating a real project and reverting changes after checking. \
You can write unit tests for your functions and scripts before use it in real projects or share with a lot of colleges

It is easy to write migrations with ng-morph. You just need to invest time in your team once, and then this tool will save you several hours every week.

ng-morph has 1.6kk downloads on NPM in the last year. It is open source and fully free.

How to use it in your project

Well, let’s take a look at two common cases for ng-morph.

The first one is for library developers. If you want to publish breaking changes updates for your library, it is much better to add an “ng update” schematic that will make migrations of your users automatic and save a huge amount of time in total. For example, Taiga UI has used ng-morph to add such a migration for a major 3.0 release with many breaking changes. In such a big library even if you ask developers to do 1 minute manual migration in your project, it’ll take hundreds of working hours in total. You can find guidelines on how to use it in schematics in our docs.

The second case is writing migrations for your own project and this is a case that I want to show you in this article. You can write a simple script in any place of your project and run it with something like ts-node immediately.

import {
  setActiveProject,
  createProject,
  getImports,
  NgMorphTree,
} from 'ng-morph';

/**
 * set all ng-morph functions to work with the all TS and JSON files
 * of the current project
 * */
setActiveProject(
  createProject(new NgMorphTree(), '/', ['**/*.ts', '**/*.json'])
);

/**
 * This simple migration gets all imports from the project TS files and
 * replaces 'old' substring with 'new'
 * */
const imports = getImports('some/path/**.ts', {
    moduleSpecifier: '@morph-old*',
});

editImports(imports, importEntity => ({
    moduleSpecifier: importEntity.moduleSpecifier.replace('old', 'new')
}));

/**
 * All changes are made in a virtual project.
 * You can save them when it is time
 * */
saveActiveProject();

Before reading about some real migrations, you can check our Stackblitz playground, run project migrations there and see how it works in real life.

Project migrations

Let’s take a look at an example on how easy it can be with ng-morph to make global changes in your project.

constructor -> inject

All right, Angular introduced using inject function in components and now we can replace type inaccurate constructor injection with it. Let’s write a ng-morph script in 30 minutes that migrates all the components in our project to the new approach.

const components = getClasses('**/*.ts', {
 name: '*Component',
});

We can get all components in several ways. The totally right way is to find all the classes with decorator Component that are imported from the “@angular/core” package. But my idea is that usually we do not need such an overengineering approach writing simple migrations scripts inside our own project if we can get the same result faster.

components is an array of AST entities. We can iterate it using .forEach.

First of all, let’s skip the classes that do not inject anything. We can use the getConstructors function with our class to get its constructor. After it we can process the result with getParams function that will return us each injected param.

components.forEach((component) => {
   const constructorParams = getParams(getConstructors(component));

   if (constructorParams.length === 0) {
     return;
   }
}

We should also add an inject function to our imports from “@angular/core”. This is how we can get all the imports and add a new one.

function fixInjectImport(file: string) {
 const angularCoreImports = getImports(file, {
   moduleSpecifier: '@angular/core',
 });

 editImports(angularCoreImports, (entity) => ({
   namedImports: [...entity.namedImports, 'inject'],
 }));
}

All we need to do is add new properties to the class and remove them from the constructor. This is how it looks in code:

components.forEach((component) => {
 const constructorParams = getParams(getConstructors(component));

 if (constructorParams.length === 0) {
   return;
 }

 fixInjectImport(component.getSourceFile().getFilePath());

 addProperties(
   component,
   constructorParams.map((param) => ({
     name: param.getName(),
     type: param.getTypeNode().getText(),
     isReadonly: param.isReadonly(),
     scope: param.getScope(),
     initializer: `inject(${
       param.getDecorator('Inject')?.getArguments()[0].getText() ??
       param.getTypeNode().getText()
     })`,
   }))
 );

 constructorParams.forEach((param) => {
   param.remove();
 });

 console.log(component.getSourceFile().getText());
});

I think there are no questions around a constructor params removing part. Let’s take a look at the addProperties function. This function takes a class (or classes) and a properties array to add to the class. We want to keep property with the same name, type, readonly status and scope (private/public/protected) as it was in param. And we need to initialize it with the default value that will be inject function with a token from Inject decorator if there is one, or from the type as a fallback. Actually, that is it, we can start the script and see how it migrates our project.

A task for you to try ng-morph

You can play with this example on Stackblitz and see how it works now.

You can also modify the script to handle @Optional and @Self DI decorators as well. It should not take much time even with no docs and if you've never used ng-morph before.

To be continued…

ng-morph can become your faithful friend when it comes to global changes in your project or routine work. So, don’t forget to give a star on Github and try to use it once you need it.

If it does not have something you need for smooth and easy migration, feel free to create an issue to let us help. By the way, you can also contribute it yourself because it is a great opportunity to learn more about your project structure from a compiler perspective. We have a CONTRIBUTING.md file with all the guidelines you need to start.

This is the first of three articles about ng-morph powers, so stay tuned here or on Twitter: @marsibarsi

If you want to get an expert help in big migrations of your project or make your developer experience better and faster, visit ng.consulting page

Taiga UI is a new Angular UI Kit that you should try

Roman Sedov — Tue, 19 Jan 2021 08:06:23 +0000

Hey, Angular devs!

@waterplea and I write articles about Angular on different blogs from time to time. We wrote almost all of them based on our experience of developing a big UI component library. We've been developing, refactoring and growing it for several years and testing our ideas on a big number of projects in our company.

We are happy to announce that we published our library into open source!

In this article I want to write about concepts and practices that we build our library with and tell you why you should try it for both new and old projects even with other components or UI libraries.

Completely modular

Let’s start with project organization. Taiga UI includes several layers of abstractions as separate packages.

@taiga-ui/cdk

It is a fundamental package. There are many Angular directives, services, tokens, base classes and utils for more safe, abstract and easy work with Angular. This package can be used as an additional multi-tool for your Angular application of any complexity. It can be also a basis for creating your own UI Kit.

Examples of entities:

TuiDestroyService to simplify “destroy$” subjects in components
TuiFilterPipe and TuiMapperPipe to handle values in a template without extra ChangeDetection cycles
tuiPure decorator to memoize getters or class methods

Our “cdk” is different from “@angular/cdk”. It is not a problem to use both of them, because it is not alternative, but addition

@taiga-ui/core

This package includes basic components for building an interface and some tools to make apps easier. Here you can find things like root components, portals for dialogs and dropdowns, theming and animations. Core is a foundation for other packages with UI components. Design and common styles start here.

@taiga-ui/kit

It is a large package that includes many components for building any interface. There are both simple components like avatar, tag or toggle and also composite as for example an input date component that is built with three basic components: textfield with a mask, dropdown and calendar.

@taiga-ui/addon-*

Addons are several thematic packages that are built with cdk, core and kit. There are for example charts package, commerce package for working with currencies, money and card input. There is also a specific doc package that give tools to build your own demo portal as ours (the link will be below 🙂)

We have the following structure with high-level packages built with base packages:

Here comes an important question: why do I need to install several packages as dependencies if I only need a couple of components? What is their size?

Well, we rewrote the structure of our libraries a few months ago. We moved all our packages to the Secondary Entry Points concept.

But we also needed to keep the previous API of imports from the root of the package. That is why we built it in a unique way where every folder deeper is a Secondary Entry Point for the folder higher.

Now all our packages give an opportunity to import entities both from Primary Entry Point and any level of depth.

By the way, the first option is sufficient because nesting can be solved by builder automatically. You do not need to think about depth of import.

This way of organization give us many benefits as:

Application bundle is smaller because all libraries become fully-treeshakable
Any cyclic dependencies can be catched on library building stage
The project is structurized better, there are no extra bindings between its entities

This means that you can import even just one entity from our library and be sure that there is no redundant code in your bundle. There is no code duplication or excess dependencies.

Customizable

All styles and colors of our library are built with CSS custom properties. It allows making new custom themes easy and you can change them on the fly.

Now we offer one main theme of Taiga UI but we have plans to create several simple and several unusual themes.

If you want to customize a single component, there are also some methods to do that. In theory, you can redesign our Kit for your design system in a few hours and use it without worrying because we don’t make breaking changes in CSS-variables too to prevent layout bugs. For example, our company is already using a separate proprietary theme on top of the open source code.

Agnostic

We want to make our components so that every developer could adjust it for their specific case fast and easy.

We do not try to envision every use case. Instead, we do not restrict appearance and use generics so components are not limited to a particular data model. You can read more about such concepts in the article by Alex Inkin “Agnostic components in Angular”.

Nevertheless, we take care of basic UX aspects to let you focus on your project features. For example, when the user focuses our textfield with a keyboard, it will show a hint after a second automatically to let the screen reader read it.

Well engineered

We respect the best developer practices and try to follow the Angular way in development of our libraries.

We are not afraid of DI, all our components use OnPush and the whole project is developed with strict TypeScript mode (we are very sensitive about typings). If you want to use SSR one day, our components will work correctly.

You do not need to worry about unexpected values of wrong types from our components or utils. Our components even print asserts in dev mode if you pass incorrect data to them :)

Read more Angular tips & tricks in my twitter: @marsibarsi

It’s big!

We have 130+ components, 100+ directives, dozens of tokens, utils and tools.

Right now you can build almost any idea of your interface quickly. And it isn't over yet: we have some ideas of next components and we are open to your requests.

How to start using Taiga

Visit our official website with documentation. Here you can see a demo of our components, learn about our libraries and find instructions how to add it into your project: taiga-ui.dev

If you want to support us or see our progress, give a star and follow Taiga UI on Github. There you can ask any questions, propose an idea or contribute to our code.

We also have a channel in Angular discord. Feel free to contact us there!

It's not goodbye

We want to write more articles about how we organize and develop our libraries. Such articles can help you understand better how our UI Kit works. They will also explain all our tricks and practices of developing easy reusable components on Angular that are very helpful in application development too.

Tell us your opinion about Taiga UI and share your ideas about which components, tools or processes you want to read first

How to Stop Worrying and Start Opensource (with a good deploy, CI and demo)

Roman Sedov — Tue, 07 Jan 2020 20:16:43 +0000

So you made a new cool thing and you get an idea to share it in open-source and to publish on NPM.

You cannot just publish your code in a public repository. It will doom the project to a lack of development and failure. On the other hand, you know there’s a lot of collateral work: versioning and publishing of package, setting up Continuous Integration, hosting and deploy for project demo, organizing community contribution.

If you just want to publish a small package, such amount of work can scare you away. The bright idea of sharing something useful will get buried in a box labeled «complicated tasks».

Actually, all of this can take you less than an hour. Without any knowledge of DevOps and for free.

Versioning

If your library is ready for its first release, you can use standard-version. This package will be fully responsible for the versioning of your library. It will bump versions of package.json, generate CHAGELOG.md file and add tags for your git history.

It manages CHANGELOG.md using Conventional Commits. This also means you will have a clear commit message format in your package. It is helpful for you and any developer who decided to contribute to your project.

Using standard-version is easy. How to use it is described in detail on the Github page. We can also add a set of release commands into our package.json to make our releases more convenient:

"release": "standard-version",
"release:patch": "npm run release -- --release-as patch",
"release:minor": "npm run release -- --release-as minor",
"release:major": "npm run release -- --release-as major",

Organizing CI

I suggest using Travis CI for Continuous Integration. It is friendly to users:

Login through Github
Choose your project from the list and activate Travis in it
Add a simple config in the root folder of the project. Travis will execute this config on CI

    language: node_js
     node_js: - "10"
    script:
     - npm run lint
     - npm run build
     - npm run test:ci

The basic CI is ready. Travis will run linters, build a project and run tests after every update of your repository.

You can also see the state of all your branches and Pull Requests and analyze each running build.

Other developers will feel more confident using your package because all your code is tested.

We can delegate code coverage control to an application-specific service Coveralls. Travis will send the result of tests after each CI build.

We just need to login to Coveralls and turn it on for a repository. Like in Travis.

Work on the project side:

Set up Coveralls as a dev-dependency of your project
Add the script for running coveralls and add it to test:ci command

    "test:ci": "npm run test && npm run coveralls",
    "coveralls": "cat coverage/lcov.info | coveralls",

Do not forget about a --code-coverage flag in your npm run test script. Coveralls needs your file lcov.info that your test runner generates. If you do not have such a flag, you can use istanbulJS package.

Work on the Travis side:

If your repository is public, you can set it up with a couple of new strings in .travis.yml:

    notifications:
       webhooks: https://coveralls.io/webhook

In any other case you can bind them using a token:

Go to repository settings on Coveralls and generate Repo Token:
Add the token as environment variable called COVERALLS_REPO_TOKEN in repository settings on Travis:

The token binds these two services. Now we can also protect the master-branch of our project:

Go to Github repository -> Settings -> Branches
Create a new rule for all branches: *
Turn on status checks. Now you cannot merge a pull request into master until Travis and Coveralls gave you green lights

Now we can turn back to *Coveralls *settings. There is a section “PULL REQUESTS ALERTS”. You can set a level of code coverage decrease that will trigger failing a build of your CI. Do it to be sure that your package is well tested.

Improve workflow

All code in your project should follow the same coding convention. Otherwise, the code base will gradually degrade and it will be harder for you to mantain the project. Do not forget that other developers are not very interested in your code style guide. That is why you need to automize this issue.

Firstly, check that you have .editorconfig file in your project folder and there are settings on how to format your code.

After that, you should install the following dev-dependencies: husky and lint-staged. The first one calls your scripts on git hooks. The second one runs your linters only for files that are staged for commit.

For example, a sample of settings for a package with TypeScript and Less:

{
   ...
   "scripts": {
       ...
       "typecheck": "tsc --noEmit --skipLibCheck",
   },
   "husky": {
       "hooks": {
           "pre-commit": "lint-staged && npm run typecheck"
       }
   },
   "lint-staged": {
       "*.{js,ts,html,md,less,json}": [
           "prettier --write",
           "git add"
       ],
       "*.ts": "tslint",
       "*.less": "stylelint"
   }
}

If you do not have any linters in your project, I can recommend you:

Prettier for code formatting
eslint or tslint as a linter for JS/TS files
stylelint for files with styles

There are many ready to use configs for them on Github that take into account all important linting rules. For example, you can take our solution: @tinkoff/linters

Publish on NPM

And now it is time to publish your package. Add one simple script to package.json:

"publish": "npm run build && npm publish ./dist"

In this case, our repository contains source code and dev files, but NPM gets only a compiled package without anything else.

We build and publish. Cool!

And furthermore, you can create some scripts that will help you with publishing. For example, let’s use NPM-hooks and add postbuild script that will copy README.md file to the dist folder. So we will not forget to update the package description on NPM.

    "build": "..",
    "postbuild": "node scripts/postbuild.js",

Set up demo

Not every package needs a demo page. If your package has a couple of methods in its public API that is well documented, you can skip this part.

In other cases, it would be better to show something. Do not forget that we publish a library. The typical demo on Github pages is not the best option for us. It is more convenient for developers to open your demo in some online IDE: they can see how to work with a package, change something or test a worrying case.

You can make a demo in another repository or just put it into a new folder near your project. We don’t even have to set up a deploy! Modern online IDEs can pull your projects or their single branches/folders from Github.

Some services that allow you to open your project in a couple of minutes:

stackblitz.com can open Angular, React, Ionic, TypeScript, RxJs and Svelte. The information about how to open your project from Github with one link is here.
codesandbox.io can open Angular, React, Vue and compile JavaScript. Here you can also open your project with a link.
repl.it is a service that can import a repository with NodeJS, Express, NextJS, GatsbyJS. TypeScript and vanilla JS are also available.

You can choose any option, add a link in your README.md and forget about setting a demo page. All updates will work automatically.

You can also add a script to CI that will build a demo with the last version of the package in NPM. It can be an additional check that an actual version works well on an external package.

Final touches

Add badges into README.md. It is a little thing but it helps a visitor of your package to navigate on Github.

For example, there are four badges saying that the project is built and has good code coverage, you can access NPM in one click.

I recommend using a service Shields.io to generate badges. They are simple and of high quality.

Summary

Such a set of tools is enough to give a good start for your project. An occasional visitor on NPM or Github will take your project more likely because it is well-described and has a good demo page.

This foundation will allow you to accept external Pull Requests restfully. Other developers will fork it without issues. Now you can focus on the implementation of the package itself, without worrying about the processes around its development.