ihg-ng-common-pages

This ihg-library-seed is used to create a standalone Angular library in seconds.

If you want to create an Angular library with directives, services and/or pipes, then this seed is just what you need.

This seed will automatically generates a Flat ES Module, a UMD bundle, a single metadata.json and type definitions to make your library ready for AOT compilation by the consuming Angular application.

More specifically, the latest version of this generator:

• supports Angular 5
• creates and configures package.json for the development of your library
• creates and configures a second package.json for the distribution of your library
• creates and configures tsconfig.json for your editor during development
• creates and configures tslint.json for linting purposes
• creates and configures .gitignore, .npmignore and .travis.yml
• creates the main library file, a sample directive, a sample component, a sample service and a sample pipe
• configures tslint for you with codelyzer support
• creates and configures build scripts to generate a Flat ES Module (FESM), type definitions and metadata files for your library to make it ready for AOT compilation
• creates and configures build scripts to generate a Universal Module Definition (UMD) bundle to use your library in Node.js, SystemJS and with script tags (Plunker, Fiddle, etc)
• inlines templates automatically for you so you can use external HTML templates
• inlines styles automatically for you so you can use external CSS templates
• supports .scss files
• supports unit tests and code coverage
• Supports demo pages app to test the library locally

Installation

To install this library, firstly clone the seed:

$ git clone http://sdlcscm.hiw.com/scm/rts/ihg-ng-common-pages.git

cd into the library and replace the module names accordingly

$ cd ihg-ng-common-pages

• Find all the references for ihg-ng-common-pages and replace it with your project name
• Find all the references for IhgNgCommonPagesModule and replace with your Module name
• Rename ihg-ng-library-see.module.ts with your project module.

Finally install all the packages, run:

$ npm install

• The 'src' folder contains all the common components in your library
• The 'demo' folder contains the components just to test the library components

Execute/Test your library code using demo pages

If you want to test the common components while you develop, run:

$ npm run demo

This above command will run the demo pages as well as unit tests together, watches for the changes and reloads the browser automatically. If you only want to run the demo pages, run:

$ npm run serve

Building your library

From the root of your library directory, run:

$ npm run build

This will generate a dist directory with:

• a package.json file specifically for distribution with Angular listed in the peerDependencies
• sample-library.js: a Flat ES Module (FESM) file that contains all your library code in a single file
• sample-library.umd.js: a Universal Module Definition (UMD) bundle file that contains all your library code in UMD format for use in Node.js, SystemJS or via a script tag (e.g. in Plunker, Fiddle, etc)
• *.d.ts: type definitions for you library
• sample-library.metadata.json: metadata for your library to support AOT compilation

TypeScript config

The generator creates 2 TypeScript config files:

• tsconfig.json is used to configure your editor during development and is not used for building your library
• src/tsconfig.es5.json is used by the Angular compiler to build the files in the dist directory when you run npm run build

Update Common

Once you install common and want to update it, run:

$ npm update ihg-ng-common-pages

Test common components using demo pages

If you want to test the common components while you develop, run:

$ npm run demo

To create a new component/pipe/service/class inside demo pages using angular-cli

You can use angular cli to create a component/services etc.. but here we have two apps in one project (common components and demo pages)

To create a component/services inside demo pages, run:

$ ng g c my-new-component --app common-demo
$ ng g s my-new-service --app common-demo

Unit Test Library Components

If you want to unit test the common components, please run the below code. It also watches for the changes while you develop.

Try to run tests and watch them while you develop

$ npm test

Unit Test Code Coverage

After running the tests, we need to see the code coverage, just to check to what percent we have covered the testing.

For that, please run the below code

$ npm install -g http-server
$ npm run test:coverage

Consuming your library

Once you have published your library to npm, you can import your library in any Angular application by running:

$ npm install ihg-ng-common-pages

If you have want to use this libraby from git/bit bucket, you can import your library in any Angular application by adding this to you package.json:

"ihg-ng-common-pages": "git+http://sdlcscm.hiw.com/scm/rts/ihg-ng-common-pages.git#master",

and then from your Angular AppModule:

import { BrowserModule } from '@angular/platform-browser';
import { NgModule } from '@angular/core';
 
import { AppComponent } from './app.component';
 
// Import your library
import { IhgNgCommonPagesModule } from 'ihg-ng-common-pages';
 
@NgModule({
  declarations: [
    AppComponent
  ],
  imports: [
    BrowserModule,
 
    // Specify your library as an import
    IhgNgCommonPagesModule.forRoot()
  ],
  providers: [],
  bootstrap: [AppComponent]
})
export class AppModule { }

Once your library is imported, you can use its components, directives and pipes in your Angular application:

<!-- You can now use your library component in app.component.html -->
<h1>
  {{title}}
</h1>
<sampleComponent></sampleComponent>

Lint all files

To lint all *.ts files:

$ npm run lint

Consuming ihg-ng-common-pages library in a local application during development

To consume your library in a local application before you publish it to npm, you can follow the following steps:

1. Navigate to the ihg-ng-common-pages directory:

$ cd ihg-ng-common-pages

1. Compile your library files:

$ npm run build

1. From the ihg-ng-common-pages/dist directory, create a symlink in the global node_modules directory to the dist directory of your library:

$ cd dist
$ npm link

1. Navigate to the ihg-ng-rpcp directory:

$ cd ihg-ng-rpcp

1. From the ihg-ng-rpcp directory, link the global ihg-ng-common-pages directory to node_modules of the ihg-ng-rpcp directory:

$ npm link ihg-ng-common-pages

1. Import IhgNgCommonModule in your Angular application:

import { BrowserModule } from '@angular/platform-browser';
import { NgModule } from '@angular/core';
 
import { AppComponent } from './app.component';
 
// Import your library
import { IhgNgCommonModule } from 'ihg-ng-common-pages';
 
@NgModule({
  declarations: [
    AppComponent
  ],
  imports: [
    BrowserModule,
    
    // Specify your library as an import
    IhgNgCommonModule.forRoot()
  ],
  providers: [],
  bootstrap: [AppComponent]
})
export class AppModule { }

1. Once your shared library is imported, you can use its components, directives and pipes in your Angular application templates:

<!-- app.component.html -->
<h1>{{ title }}</h1>
<sample-component>
  This component is part of the shared library and will now work as expected.
</sample-component>

and if you need to access a service from your shared library, you can inject it using Dependency Injection:

import { Component } from '@angular/core';
 
// Import the shared service
import { IhgNgCommonModule } from 'ihg-ng-common-pages';
 
@Component({
  template: 'Injecting a service from the shared library'
})
export class HomeComponent {
 
  // Inject the service using Angular DI 
  constructor(private sampleService: SampleService){
  
  }
 
}

1. When you make a change to your library, recompile your library files again from your ihg-ng-common-pages directory:

$ npm run build

1. If you want to automatically recompile the library files when a file in src changes, run

$ npm run build:watch

1. If you are using an Angular CLI application to consume your library, make sure to set up a path mapping in /src/tsconfig.app.json of your consuming application (not your library):

{
  "compilerOptions": {
    // ...
    // Note: these paths are relative to `baseUrl` path.
    "paths": {
      "@angular/*": [
        "../node_modules/@angular/*"
      ]
    }
  }
}

When you npm link a library with peer dependencies, the consuming application searches for the peer dependencies in the library's parent directories instead of the application's parent directories.

If you get Error: Unexpected value '[object Object]' imported by the module 'AppModule'. Please add a @NgModule annotation., then try:

$ ng serve --preserve-symlinks

to make sure the consuming application searches for the peer dependencies in the application's node_modules directory.