@ngstack/install

Install

Command-line utility for installing Angular libraries into the Angular CLI-based projects.

Main features

• Install library from the NPM or local package (i.e. tarball file)
• Register assets, styles and scripts with angular.json
• Register library modules in the application
• Format updated application module with Prettier
• Generate new configuration file for a library

Getting the tool

Install as a global package using the following command:

npm i -g @ngstack/install

You can use the tool everywhere using ngi alias.

Options

Run ngi without parameters to see the internal help.

Name	Description
-v, --version	output the version number
-n, --name <name>	set library name if installing from custom sources (default: null)
--init	create a new configuration file
--module <module>	module to use for the registration (default: app)
--import [modules]	list of modules to import
--skip-install	skip installing library
--skip-assets	skip copying assets
--skip-module	skip module registration
--skip-format	skip code formatting
-h, --help	output usage information

Preparing libraries

Add and publish an ngi.json file as part of your library.

Example:

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

Based on the configuration above, the tool is going to perform the following actions:

• copy all JSON files from assets to the assets/plugin folder
• generate import { MyExtensionModule } from 'my-extension'; in the /src/app/app.module.ts
• put the MyExtensionModule into the module imports section

Asset configuration

The asset configuration format is based on the Angular CLI settings. However, the input property defines the path relative to the library structure, rather than application one.

{
  "glob": "**/*.json",
  "input": "./assets",
  "output": "./assets/plugins"
}

Styles and Scripts

You can also register custom styles and scripts in the corresponding sections within angular.json file.

Example (ngi.json):

{
  "styles": ["./styles/one.css", "./styles/two.css"],
  "scripts": ["./scripts/test1.js", "./scripts/test2.js"]
}

Upon execution the ngi tool is going to use relative paths to the extension folder.

Example (angular.json)

{
  "styles": [
    "node_modules/my-extension/styles/one.css",
    "node_modules/my-extension/styles/two.css"
  ],
  "scripts": [
    "node_modules/my-extension/scripts/test1.js",
    "node_modules/my-extension/scripts/test2.js"
  ]
}

Installing arbitrary libraries

The tool works best with the ngi.json configuration files that are published with the libraries. However it is also possible to install an arbitrary Angular library.

In this case you need to provide one or multiple module names to import.

ngi @company/library --import=Module1,Module2

As a result of the command above, the tool is going to install @company/library from the NPM, and setup the main application module with two imports:

import { Module1 } from '@company/library';
import { Module2 } from '@company/library';

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

Note that you will have to setup asset rules for angular.json file manually.

Examples

Install library my-extension from the NPM and perform integration tasks if ngi.json file present.

ngi my-extension

Install library from the tarball generated by the npm pack command. Use my-extension name to find and use library in the node_modules.

ngi my-extension-0.0.1.tgz my-extension

Perform only application module integration for manually installed library

ngi my-extension-0.0.1.tgz my-extension --skip-install --skip-assets

License

MIT