Denys Vuika's Blog

Denys Vuika

Announcing ngi: installer for Angular libraries

October 07, 2018

Today I am very excited to announce a new tool for Angular CLI projects called “ngi”.

It is a command-line utility that provides a way to install 3rd party Angular libraries based on simple conventions.

The tool is published to NPM and you can use it alongside the ng tool from the Angular CLI. Check the official readme for more details: https://www.npmjs.com/package/@ngstack/install.

The problems addressed

The Angular Schematics, announced nearly a year ago, is still an experimental project. In its current state it is highly over-engineered and undocumented project, requires developers write a lot of code to support ng add command for their libraries, especially when it comes to NgModule registration.

There’s a great book to get more details on the Schematics if you are interested: https://leanpub.com/angular-schematics.

You will notice, however, that the development and project maintenance process is not trivial.

The main focus of the ngi tool is to automate the installation process and eliminate the need for writing an extra code for simple integration operations.

Simple convention

The ngi tool does not force you to write large amounts of code just to copy an asset file from published library to the application, or update the application module with corresponding Module import.

Instead, it relies on a simple convention and a configuration file that helps automating basic deployment operations:

  • install library from the NPM or local tarball package
  • copy multiple files to the application assets folder
  • generate import declaration and update app.module.ts or other modules

The only thing you need to enable support for feature above is put an ngi.json file to the root of your project library, and ship it alongside other files when publishing to NPM.

The ngi tool installs a library like you would typically do with npm install command, and performs a set of integration tasks if ngi.json file is present.

Example of the ngi.json file you ship with your Angular libraries:

{
  "assets": [
    {
      "glob": "**/*.json",
      "input": "./assets",
      "output": "./assets/plugins"
    }
  ],
  "modules": [
    {
      "name": "MyExtensionModule",
      "namespace": "my-extension"
    }
  ]
}

Let’s imagine you have published a library called my-extension with the ngi.json file above. You can now install it using a simple command like following:

ngi my-extension

Upon installation, the ngi tool registers corresponding asset rules in the angular.json file for both “build” and “test” configurations. So you can upgrade dependency and get new assets on the fly.

The asset configuration format is similar to that of the Angular CLI. The only difference is that ngi uses an input path relative to the library root, not the workspace.

Next, it will go through the the modules section and update app.module.ts with the corresponding declarations, for example:

import { MyExtensionModule } from 'my-extension';

@NgModule({
  imports: [MyExtensionModule],
})
export class AppModule {}

All existing modules will remain the same, the ngi just puts the code to proper places and saves the file.

You can use the tarball packages (created by the npm pack command) for local testing without NPM:

ngi my-extension-0.0.1.tgz my-extension

What’s next

More features will be added based on the feedback and contributions. Make sure you leave requests, ideas or pull requests here: https://github.com/ngstack/install.