How to build your own Angular component library with DevUI

Preface

As a front-end developer, as the company's business continues to develop and grow, the business will have more and more demands on component functions and interactions, and there will be more and more common components between different products or teams. At this time, you need a set of component libraries to support internal use, or you can expand or encapsulate some native third-party libraries based on existing components. This article will teach you step by step how to build your own Angular component library.

Creating a component library

We first create an Angular project to manage the display and release of components. Use the following command to generate a new project

ng new <my-project>

After the project is initialized, enter the project and run the following cli command to initialize the lib directory and configuration, and generate a component library skeleton.

ng generate library <my-lib> --prefix <my-prefix>

my-lib is the library name specified for yourself, such as devui, my-prefix is ​​the component and instruction prefix, such as d-xxx, and the default generated directory structure is as follows

In the angular.json configuration file, you can also see that there is an additional configuration for the project type library under projects.

"my-lib": {
  "projectType": "library",
  "root": "projects/my-lib",
  "sourceRoot": "projects/my-lib/src",
  "prefix": "dev",
  "architect": {
    "build": {
      "builder": "@angular-devkit/build-ng-packagr:build",
      "options": {
          "tsConfig": "projects/my-lib/tsconfig.lib.json",
          "project": "projects/my-lib/ng-package.json"
      },
  "configurations": {
    "production": {
      "tsConfig": "projects/my-lib/tsconfig.lib.prod.json"
    }
  }
},
...

Key configuration changes

Directory layout adjustment

From the directory structure, we can see that the default generated directory structure is relatively deep. Referring to material design, we customize the directory structure as follows:

Modification Notes:

• Delete the src directory under the my-lib directory, copy test.ts from the src directory, and use it as the entry point for the component library test file
• Flatten the components into the my-lib directory, and add my-lib.module.ts (for managing the import and export of components) and index.ts (export my-lib.module.ts to simplify import) in the my-lib directory
• Modify the sourceRoot path under my-lib in angular.json to point to my-lib

Modify as follows:

// my-lib.module.ts


import { NgModule } from '@angular/core';
import { CommonModule } from '@angular/common';
import { AlertModule } from 'my-lib/alert'; // Import here according to the on-demand import method, my-lib corresponds to our release library name @NgModule({
  imports: [ CommonModule ],
  exports: [AlertModule],
  providers: [],
})
export class MyLibModule {}


// index.ts
export * from './my-lib.module';


//angular.json
"projectType": "library",
"root": "projects/my-lib",
"sourceRoot": "projects/my-lib", // The path here points to our new directory "prefix": "devui"

Key configuration for library construction

ng-package.json configuration file, the configuration file that angular library depends on when building

{
  "$schema": "../../node_modules/ng-packagr/ng-package.schema.json",
  "dest": "../../publish",
  "lib": {
    "entryFile": "./index.ts"
  },
  "whitelistedNonPeerDependencies": ["lodash-es"]
}

Key configuration instructions:

• dest, lib build output path, here we change it to publish directory, separate from project build dist directory
• lib/entryFile, specifies the library build entry file, which points to our index.ts above

whitelistedNonPeerDependencies (optional). If the component library depends on a third-party library, such as lodash, you need to configure a whitelist here. Because ng-packagr checks the dependencies configuration of package.json when building to avoid the risk of multiple version conflicts in third-party dependent libraries. If a whitelist is not configured, the build will fail if there is a dependencies configuration.

For package.json configuration, it is recommended to use peerDependcies if the business also configures related dependencies.

{
  "name": "my-lib",
  "version": "0.0.1",
  "peerDependencies": {
    "@angular/common": "^9.1.6",
    "@angular/core": "^9.1.6",
    "tslib": "^1.10.0"
  }
}

For detailed and complete configuration, please refer to the official angular documentation https://github.com/ng-packagr/ng-packagr/blob/master/docs/DESIGN.md

Developing an Alert component

Component Function Introduction

We refer to the alert component of the DevUI component library to develop a component to test our component library. The alert component mainly presents different colors and icons according to the type passed in by the user, and is used to display different warning messages to the user. The visual display is as follows

Component structure decomposition

First, let's take a look at what files the alert component directory contains

Directory structure description:

• The component is a complete module (like a normal business module) and contains a unit test file
• There is a package.json in the component directory to support secondary entry (a single component supports on-demand introduction)
• public-api.ts is used to export modules, components, services, etc. It is the external exposure entry point. index.ts will export public-api to facilitate other modules

The key points are as follows:

// package.json
{
  "ngPackage": {
    "lib": {
      "entryFile": "public-api.ts"
    }
  }
}


//public-api.ts
/*
* Public API Surface of Alert
*/
export * from './alert.component';
export * from './alert.module';

Defining input and output

Next, we will start to implement the component. First, we define the input and output of the component. We pass in the alert content by projection. The Input parameter supports specifying the alert type, whether to display an icon, and whether the alert can be closed. The Output returns a close callback for the user to handle the logic after closing.

import { Component, Input } from '@angular/core';
// Define the optional types of alert export type AlertType = 'success' | 'danger' | 'warning' | 'info';


@Component({
  selector: 'dev-alert',
  templateUrl: './alert.component.html',
  styleUrls: ['./alert.component.scss'],
})
export class AlertComponent {
  // Alert type@Input() type: AlertType = 'info';
  // Whether to display the icon to support user-defined icons @Input() showIcon = true;
  // Is it possible to close @Input() closeable = false;
  // Close callback @Output() closeEvent: EventEmitter<boolean> = new EventEmitter<boolean>();
  hide = false;
  constructor() {}


  close(){
    this.closeEvent.emit(true);
    this.hide = true;
  }
}

Defining the layout

According to the API definition and visual display, we implement the page layout structure. The layout includes a close button, icon placeholder and content projection. When the component is closed, we clear the DOM.

<div class="dev-alert {{ type }} " *ngIf="!hide">
  <button type="button" class="dev-close" (click)="close()" *ngIf="closeable"></button>
  <span class="dev-alert-icon icon-{{ type }}" *ngIf="showIcon"></span>
  <ng-content></ng-content>
</div>

At this point, the page layout and component logic of our component have been encapsulated, and the development is completed based on the visual display and corresponding style processing.

Testing the Alert Component

Development reference components

During component development, we need to be able to debug logic and adjust UI display in real time. Open tsconfig.json in the root directory and modify the paths mapping to facilitate local debugging of our components in development mode. Here, my-lib is directly pointed to the component source code. Of course, you can also use the default configuration through ng build my-lib --watch to point to the built pre-release file. At this time, we need to configure it to the modified directory public/my-lib/*

"paths": {
  "my-lib": [
    "projects/my-lib/index.ts"
  ],
  "my-lib/*": [
    "projects/my-lib/*"
  ],
}

After the configuration is complete, you can use the library we are developing in the application in the npm way. We first import the components we are developing in app.module.ts. Here we can import all components from my-lib.module, or directly import our AlertModule (which has been configured to support secondary entry)

import { AlertModule } from 'my-lib/alert';
// import { MyLibModule } from 'my-lib';


@NgModule({
  declarations: [
    AppComponent
  ],
  imports: [
    BrowserModule,
    AppRoutingModule,
    // MyLibModule
    AlertModule
  ],
  providers: [],
  bootstrap: [AppComponent]
})
export class AppModule { }

At this point, you can directly use the alert component we are developing in the app.component.html page.

<section>
  <dev-alert>I am a default type of alert</dev-alert>
</section>

Open the page and you can see the effect of the current development. At this time, we can adjust the style and interaction logic according to the page performance. I will not continue to show it here.

Writing unit tests

As mentioned earlier, we have a unit test file. In order to ensure the quality of the code and the stability of the subsequent refactored components, it is recommended to add unit tests when developing components.

Since we adjusted the directory structure, let's modify the relevant configuration first

// angular.json
"my-lib": {
  ...
  "test": {
    "builder": "@angular-devkit/build-angular:karma",
    "options": {
      "main": "projects/my-lib/test.ts", // This points to the adjusted file path "tsConfig": "projects/my-lib/tsconfig.spec.json",
      "karmaConfig": "projects/my-lib/karma.conf.js"
    }
  },
}


//tsconfig.spec.json in the my-lib directory  


"files": [
  "test.ts" // points to the test entry file in the current directory]

The following is a simple test reference, which simply tests whether the type is correct. The components to be tested are defined in the test file. When there are many scenarios, it is recommended to provide a demo and use the demo directly to test different scenarios.

import { async, ComponentFixture, TestBed } from '@angular/core/testing';


import { Component } from '@angular/core';
import { AlertModule } from './alert.module';
import { AlertComponent } from './alert.component';
import { By } from '@angular/platform-browser';


@Component({
  template: `
    <dev-alert [type]="type" [showIcon]= "showIcon"[closeable]="closeable" (closeEvent)="handleClose($event)">
    <span>I am an Alert component</span>
    </dev-alert>
  `
})
class TestAlertComponent {
  type = 'info';
  showIcon = false;
  closeable = false;
  clickCount = 0;
  handleClose(value) {
    this.clickCount++;
  }
}


describe('AlertComponent', () => {
  let component: TestAlertComponent;
  let fixture: ComponentFixture<TestAlertComponent>;
  let alertElement: HTMLElement;


  beforeEach(async(() => {
    TestBed.configureTestingModule({
      imports: [AlertModule],
      declarations: [ TestAlertComponent ]
    })
    .compileComponents();
  }));


  beforeEach(() => {
    fixture = TestBed.createComponent(TestAlertComponent);
    component = fixture.componentInstance;
    alertElement = fixture.debugElement.query(By.directive(AlertComponent)).nativeElement;
    fixture.detectChanges();
  });


  describe('alert instance test', () => {
    it('should create', () => {
      expect(component).toBeTruthy();
    });
  });


  describe('alert type test', () => {
    it('Alert should have info type', () => {
      expect(alertElement.querySelector('.info')).not.toBe(null);
    });


    it('Alert should have success type', () => {
      // Modify type to determine whether the type change is correct component.type = 'success';
      fixture.detectChanges();
      expect(alertElement.querySelector('.success')).not.toBe(null);
    });
  }

We can run unit tests by executing ng test my-lib. By default, a window will open to show our test results.

At this point, the component development reference and testing are completed. If there are no problems with the functions and interactions, you can prepare to publish it to npm.

For more testing content, please refer to the official introduction: https://angular.cn/guide/testing

Release Components

After the component development is completed and the unit test meets the access control indicators we defined, it can be published to npm for other students to use.

First, we build the component library, since ng9 uses the ivy engine by default. It is not officially recommended to publish Ivy format libraries to the NPM repository. So before publishing to NPM, we build it with the --prod flag, which uses the old compiler and runtime, the View Engine, instead of Ivy.

ng build my-lib --prod

After the build is successful, you can start publishing the component library. Here we take publishing to the npm official repository as an example.

If you don't have an npm account yet, please go to the official website to register an account and choose a public type free account

If you already have an account, first confirm that the configured registry points to the npm official registry https://registry.npmjs.org/

Execute npm login in the terminal to log in to the registered user

After all the preparations are completed, go to the build directory, which is the publish directory, and then execute npm publish --access public to publish it. Note that our library name needs to be unoccupied on npm. The name is changed in package.json in the my-lib directory.

npm publishing reference: https://docs.npmjs.com/packages-and-modules/contributing-packages-to-the-registry

If it is an internal private library, just configure the registry according to the requirements of the private library, and the publishing commands are the same.

The above is the details of how to use DevUI to build your own Angular component library. For more information about DevUI to build your own Angular component library, please pay attention to other related articles on 123WORDPRESS.COM!