Angular Library Guide

Goal: create a reusable Angular library

The idea is to create Angular workspace which consists of a library and test application.

The library is code which could be published to NPM, while test application is an environment with documentation and example usage of the library.

Test subjects:

• Library name: turbo-lib
• Test application name: turbo-tester

This repository contains sample project in the turbo-lib directory which could be used as a reference.

Boilerplate

1. Make sure that Angular CLI will use the latest stable version of Angular
2. Create Angular workspace with ng new turbo-lib --create-application=false
3. Create library project
   • cd turbo-lib
   • ng generate library turbo-lib --prefix=turbo
4. Create test application project
   • ng generate application turbo-tester
   • End-to-end tests for test application are located in the projects/turbo-tester-e2e/ folder

Keep in mind that configuration for both projects is located in the angular.json file.

Building, Serving & Testing

• Build library with ng build turbo-lib
• Build test application with ng build turbo-tester --prod
• Serve application with ng serve turbo-tester
• Run library tests with ng test turbo-lib
• Run test application tests with ng test turbo-tester

Usage Goals

The goal is to achieve following:

/* Import whole library */
import * as TurboLib from "turbo-lib"

/* Import specific components and services from library */
import { TurboComponent, TurboService } from "turbo-lib"

When using published library, i.e. on NPM or Git repository, one can easily use aforementioned imports. On the other hand, while developing library, import paths should be added to tsconfig.json file.

That is, if we want to use turbo-lib inside turbo-tester application, tsconfig.json file must have the following lines:

"paths": {
    "turbo-lib": [
        "dist/turbo-lib"
    ]
}

Development

Library source files are located in the turbo-lib/projects/turbo-lib/src directory.

Keep in mind that package.json in that directory is going to be published on NPM.

On the other hand, public_api.ts is the entry file. It specifies what parts of library are visible externally.

First Steps

This section describes how to modify, i.e. create, custom library component, and how to use it in the test application.

Create library component

Due to specific requirements, this example modifies default Angular library which was generated by CLI tool.

1. Set up a listener which will build new version of library on every change
   • ng build turbo-lib --watch
2. Rename projects/turbo-lib/src/lib/turbo-lib.component.ts
   • Rename file to heading.component.ts
3. Modify heading.component.ts
   • Modify selector to turbo-heading
   • Change template to something more appropriate, i.e. `<h1>TURBO HEADING</h1>`
   • Rename class name to HeadingComponent
4. Rename projects/turbo-lib/src/lib/turbo-lib.component.spec.ts
   • Rename file to heading.component.spec.ts
   • Replace all TurboLibComponent occurences with HeadingComponent
5. Modify heading.component.spec.ts
   • Modify import to import HeadingComponent from heading.component
6. Modify projects/turbo-lib/src/lib/turbo-lib.module.ts
   • Modify component import to import { HeadingComponent } from './heading.component';
   • Replace all TurboLibComponent occurences with HeadingComponent
7. Define component in projects/turbo-lib/src/public_api.ts file
   • Remove export * from './lib/turbo-lib.component';
   • Add export * from './lib/heading.component';

When creating new component from scratch, use ng generate component component-name --project=turbo-lib.

Usage in test application

1. Serve test application with ng serve turbo-tester
2. Import TurboLibModule in main application module, i.e. projects/turbo-tester/src/app/app.module.ts
   • Add line import { TurboLibModule } from "turbo-lib";
3. Use sample component in projects/turbo-tester/src/app/app.component.html
   • Add line <turbo-heading></turbo-heading>

Resources

• The Angular Library Series
• How to upgrade Angular CLI to the latest version