@vts-kit/nx-angular v1.0.10

VTS Kit Angular NX Plugin

VTS Kit Angular NX Plugin is a collection of generators to be integrated with Nx Workspace. This library aims to provide a quick way to start a new Angular Project and maintain code structure with least effort.

Requirement

• Node: 12+
• Npm: 6+ (included in Node installation)
• Npx: 6+ (included in Node installation)

Intergrated Features

• Custom Webpack (Guideline)
• UI Component: VTS UI Kit (Guideline + Home)
• Localization: @ngx-translate/core (Guideline + Git)
• Network Utilities: VTS Kit Angular Utilities (Guideline + Git)
• Validator Utilities: VTS Kit Angular Utilities (Guideline + Git)
• Common Utilities: VTS Kit Angular Common (Guideline + Git)
• Bundle Analyze: webpack-bundle-analyzer (Guideline + Git + NPM)
• CICD (Jenkin + Docker) intergrated (Guideline)
• Dynamic Environment (Guideline)
• 3rd party integration (Guideline + Git)

Quickstart

• Create a new workspace using VTS Kit Angular NX Plugin:

npx @vts-kit/nx-angular@latest

Structure

.
└── <workspace_name>/
    ├── apps/
    │   └── <app_name>/
    │       ├── src/
    │       │   ├── app/
    │       │   │   ├── app.module.ts           // Root component
    │       │   │   ├── app.component.ts        // Root component, bootstrap
    │       │   │   ├── app.component.spec.ts   // Root component, test
    │       │   │   ├── app.component.html      // Root component, outlet
    │       │   │   ├── configs.ts              // Provider, import configs
    │       │   │   └── routes.ts               // RouterModule config, lazy load to feature libraries
    │       │   ├── assets/                     // Public assets
    │       │   │   └── locale/                 // Translation dictionary
    │       │   │       ├── en.json             // JSON dictionary
    │       │   │       └── vi.json             // JSON dictionary
    │       │   ├── environments/               // Environment config
    │       │   |    ├── environment.ts         // Environment profile
    │       │   |    └── environment.prod.ts    // Environment profile
    │       │   └── styles/                     // Global styles
    │       ├── webpack/                        // Webpack config
    │       │   ├── webpack.config.js           // Webpack profile
    │       │   └── webpack.config.prod.js      // Webpack profile
    │       ├── project.json                    // Nx Project configuration
    │       ├── tsconfig(.|lib|spec).json       // Tsconfig
    │       ├── favicon.ico                     // Angular starter files
    │       ├── index.html                      // Angular starter files
    │       ├── main.ts                         // Angular starter files
    │       ├── polyfills.ts                    // Angular starter files
    │       └── test.ts                         // Angular starter files
    ├── libs/                                   // Shared modules and feature modules
    │   ├── layout/                             // Feature group, layout
    │   │   ├── ui/                             // Library (generatable)
    │   │   │   ├── src/
    │   │   │   │   ├── index.ts                // Automatically exporter on generating
    │   │   │   │   └── lib/
    │   │   │   │       ├── <topbar>            // Standalone UI components, unit (generatable)
    │   │   │   │       └── <sider>             // Standalone UI components, unit (generatable)
    │   │   │   ├── project.json                // NX Project configuration
    │   │   │   └── tsconfig(.|lib|spec).json   // Tsconfig
    │   │   ├── feature/                        // Library (generatable)
    │   │   │   ├── src/
    │   │   │   │   ├── index.ts                // Automatically exporter on generating
    │   │   │   │   └── lib/
    │   │   │   │       ├── <dasboard_layout>   // Standalone UI components, container (ultilize units in template)
    │   │   │   │       ├── <home_layout>       // Standalone UI components, container (ultilize units in template)
    │   │   │   │       ├── routes.ts           // RouterModule config, lazy load
    │   │   │   │       └── *.module.ts
    │   │   │   ├── project.json                // NX Project configuration
    │   │   │   └── tsconfig(.|lib|spec).json   // Tsconfig
    │   │   └── data-access/                    // Library (generatable)
    │   │       ├── src/
    │   │       │   ├── index.ts                // Automatically exporter on generating
    │   │       │   └── lib/
    │   │       │       └── <store_1>           // State management, store
    │   │       ├── project.json                // NX Project configuration
    │   │       └── tsconfig(.|lib|spec).json   // Tsconfig
    │   ├── <feature_product>/                  // Feature group (generatable)
    │   │   ├── ui/                             // Library (generatable)
    │   │   │   ├── src/
    │   │   │   │   ├── index.ts                // Automatically exporter on generating
    │   │   │   │   └── lib/
    │   │   │   │       ├── <product_form>      // Standalone UI components, unit (generatable)
    │   │   │   │       └── <product_table>     // Standalone UI components, unit (generatable)
    │   │   │   ├── project.json                // NX Project configuration
    │   │   │   └── tsconfig(.|lib|spec).json   // Tsconfig
    │   │   ├── feature/                        // Library (generatable)
    │   │   │   ├── src/
    │   │   │   │   ├── index.ts                // Automatically exporter on generating
    │   │   │   │   └── lib/
    │   │   │   │       ├── <list_screen>       // Standalone UI components, container (ultilize units in template)
    │   │   │   │       ├── <detail_screen>     // Standalone UI components, container (ultilize units in template)
    │   │   │   │       ├── routes.ts           // RouterModule config, lazy load
    │   │   │   │       └── *.module.ts
    │   │   │   ├── project.json                // NX Project configuration
    │   │   │   └── tsconfig(.|lib|spec).json   // Tsconfig
    │   │   └── data-access/                    // Library (generatable)
    │   │       ├── src/
    │   │       │   ├── index.ts                // Automatically exporter on generating
    │   │       │   └── lib/
    │   │       │       ├── <item_state>        // State management, store
    │   │       │       └── <filter_state>      // State management, store
    │   │       ├── project.json                // NX Project configuration
    │   │       └── tsconfig(.|lib|spec).json   // Tsconfig
    │   └── share/
    │       └── guards/                         // Library, publishable (generatable)
    │       ├── interceptors/                   // Library, publishable (generatable)
    │       ├── data-access/                    // Library, publishable (generatable)
    │       ├── pipes/                          // Library, publishable (generatable)
    │       ├── services/                       // Library, publishable (generatable)
    │       ├── ui/                             // Library, publishable (generatable)
    │       ├── utils/                          // Library, publishable (generatable)
    │       └── validators/                     // Library, publishable (generatable)
    ├── package.json
    ├── nx.json                                 // NX Workspace configuration
    └── tsconfig.base.json                      // Tsconfig, automatically update project alias

Using NX generators to generate necessary items and keep structure sync.

Generators

Schematics

Usage

Using Nx CLI

• Make sure NX CLI has been installed.

npm i -g nx

• Using VTS Kit generators.

nx g @vts-kit/nx-angular:<generator_name> <generator_args>

Using Nx Console (GUI)

• Install Nx Console in VSCode

• Using generator:

  • Option 1: Select generate Nx Console Tab and select a generator

    • Option 2: Right click on a library and select nx generate in context menu

• Fill in options

• Preview changes

• Press Run to make changes

Generator: Library

Generator: Feature Group

Generator: Component

Generator: Directive

Generator: Pipe

Generator: Service

Generator: Class

Generator: Interface

Generator: Enum

Generator: Guard

Generator: Interceptor

Generator: Resolver

Generator: Validator

Generator: Template

Feature Guideline

Feature: Custom webpack

Custom webpack unlock the ability to enhance web builder process.
VTS Kit Angular provides 2 profile of webpack on generating project. You find these files under app/<app_name>/webpack.config.<profile>.js.
You can also add another profile, but take note to register profile in app/<app_name>/project.json

Feature: UI Component

Please see full guideline in https://design.atviettelsolutions.com/uikit/

Feature: Localization

Translation dictionary can be found under app/<app_name>/src/assets/locale/. By default, VTS Kit generate 2 translation files which are Vietnamese and English. If you want to add new language, just create new JSON file under this folder and use TranslateService to use new language.

Config (Already declared on generating, maybe be overwritten)

Translation config is localed in app/<app_name>/src/app/configs.ts.

// configs.ts

import { TranslateLoader, TranslateModuleConfig } from '@ngx-translate/core';

class TranslateHttpLoader extends TranslateLoader {
  getTranslation(lang: string): Observable<any> {
    return from(fetch(`./assets/locale/${lang}.json`).then((d) => d.json()));
  }
}

export const TRANSLATE_MODULE_CONFIG: TranslateModuleConfig = {
  defaultLanguage: 'vi',
  loader: {
    provide: TranslateLoader,
    useClass: TranslateHttpLoader,
  },
};

By default, translation module is configured to use HTTP loader to load translation file from assets and use vi language.

Import (Already imported on generating)

// app.module.ts
@NgModule({
  imports: [
    TranslateModule.forRoot(TRANSLATE_MODULE_CONFIG)
  ]
})

Usage

• Switch language

constructor(private translateService: TranslateService) {
  this.translateService.use('en')
}

• Get current language:

this.translateService.currentLang;

• Get translate:

Example dictionary

{
  "hello": {
    "world": "Xin chào {{name}}"
  }
}

Get translation using service

// Return value of string => Xin chào A
// Note: instant() require the TranslateModule has been loaded, if you're unsure about this, use get() or pipe
this.translateService.instant('hello.world', { name: 'A' });

// Return Observable of value of string
this.translateService
  .get('hello.world', { name: 'A' })
  .subscribe((d) => console.log(d)); // d = 'Xin chào A'

Get translation using pipe

// Will render paragraph of "Xin chào A"
<p>{{ 'hello.world' | translate:{name: 'A'} }}

Feature: Network

VTS KIT provides easy-to-config RestClient to interactive with RESTful API and some other network utilities.

Config (Already declared on generating, maybe be overwritten)

Network config is localed in app/<app_name>/src/app/configs.ts.

// configs.ts
import {
  RestClientOptions,
  VtsRestModuleConfig,
} from '@vts-kit/angular-network';

const NETWORK_MODULE_CONFIG: VtsRestModuleConfig = {
  defaultConfig: new RestClientOptions()
    .setBaseUrl('https://<base_api_url>')
    .setHeader('key', 'value')
    .setParam('key', 'value')
    .setRetry(3),
};

Import (Already imported on generating)

// app.module.ts
@NgModule({
  imports: [
    TranslateModule.forRoot(TRANSLATE_MODULE_CONFIG),
  ]
})

Usage

Pattern

client
  .setHeader("key", "value")
  .setTimeout(60000)
  ... // More builder
  .obserseBody() // or obserseEvents() or obserseResponse()
  .get("<path or url>") // or post, patch, put, options, delete
  .subscribe(...)

Example

// name.any.ts
import { RestClient } from '@vts-kit/angular-network';

@Injectable({
  providedIn: 'root',
})
export class Service {
  constructor(private client: RestClient) {}

  callApi() {
    this.client
      .obserseBody()
      .get<Post[]>('/posts')
      .subscribe({
        next: (d) => console.log(d[0].title),
        error: (e) => console.log(e),
      });
  }
}

Feature: Validation

VTS KIT provides common validation function to be used combine with Angular Validator to make form validation easier.

List of validator

Usage

For template-driven form:

// *.ts
import { VtsValidatorModule } from '@vts-kit/angular-validator';

@(NgModule | Component | ...)({
    imports: [VtsValidatorModule]
})

// *.html
<input ngModel url  />
<input number [larger]="5" [smallerOrEqual]="10" #control="ngModel">

// You can see raise errors here
{{ control.errors | json }}

For reactive form:

// *.ts
import { VTSValidators } from '@vts-kit/angular-validator';

export class Component ... {
  // Use with 'validators' property of FormControl, FormGroup, FormBuilder, ...
  control1 = new FormBuilder().control('', {
      validators: [VTSValidators.url]
  })

  control2 = new FormBuilder().control('', {
    validators: [
        VTSValidators.number({
          larger: 5,
          smallerOrEqual: 10
        })
    ]
  })
}

// *.html
<input [formControl]="control1" />
<input [formControl]="control2" />

// You can see raise errors here
{{ control1.errors | json }}
{{ control2.errors | json }}

Feature: Common

VTS KIT provides common utility function to help code faster.

Date

String

Path

Feature: Bundle Analyzer

VTS KIT integrated bundle analyzer to help auditing overall bundle size.

Config (Already declared on generating, maybe be overwritten)

Webpack bundle analyzer config is localed in app/<app_name>/webpack/webpack.configs(.prod).ts.

const BundleAnalyzerPlugin = require('webpack-bundle-analyzer').BundleAnalyzerPlugin;

module.exports = (config, context) => {
  return merge(config, {
    plugins: [
      // Other plugins
      ...(process.env.ANALYZE
        ? [
            new BundleAnalyzerPlugin({
              analyzerMode: 'server',
              analyzerHost: '127.0.0.1',
              analyzerPort: 8001,
            }),
          ]
        : []),
    ]
  })

By default, webpack bundle analyzer will serve a web report at http://127.0.0.1:8001. You can check out more options for webpack bundle analyzer here

Usage

Either use VTS Kit script inside package.json or custom your own.

// package.json
  ...
  scripts: {
    "start:analyze": "cross-env ANALYZE=1 npm run start",
    "build:analyze": "cross-env ANALYZE=1 npm run build"
  }

Using start:analyzer to start analyzing on Development Environment or build:analyzer to analyze on Production Environment

VTS KIT provides Docker config and Jenkin config with dynamic variables, developer can make change at ease.

CICD variables can be found under cicd/jenkinsfile/environment.groovy. Developer have to fill out all required fields to make it work in jenkine pipeline.

/** Pipeline options **/
env.flag_sonar = ""                                         // OPTIONAL, Enable sonar scan (set to 'yes' to enable)
env.flag_security = ""                                      // OPTIONAL, Enable fortify scan (set to 'yes' to enable)

/** Application information **/
env.appName = "demo"                                        // REQUIRED
                                                            // Determine docker image name (<harborServer>/<harborProject>/<appName>:<version>_<buildNumber>)
                                                            // and deployment/service name


/** Kubernetes profile **/

// Development profile
env.devKubeConfigFileSecret = "dev-k8s-config"              // REQUIRED, Secret file credential stored on Jenkin, give in fileID
env.devNamespace = ""                                       // REQUIRED, Kubernetes namespace to deploy
env.devPort = "80"                                          // REQUIRED, Should be nginx port
env.devTargetPort = "80"                                    // REQUIRED, Container port, should be nginx port
env.devNodePort = ""                                        // REQUIRED, Exposal port for external access
env.devImagePullSecrets = "default"                         // REQUIRED, Docker secret to pull image

// Production profile
env.prodKubeConfigFileSecret = "prod-k8s-config"            // REQUIRED, Secret file credential stored on Jenkin, give in fileID
env.prodNamespace = ""                                      // REQUIRED, Kubernetes namespace to deploy
env.prodPort = "80"                                         // REQUIRED, Should be nginx port
env.prodTargetPort = "80"                                   // REQUIRED, Container port, should be nginx port
env.prodNodePort = ""                                       // REQUIRED, Exposal port for external access
env.prodImagePullSecrets = "default"                        // REQUIRED, Docker secret to pull image


/** Docker harbor configuration **/
env.pullRegistry = ""                                       // REQUIRED, Harbor registry to pull base images
env.harborProject = ""                                      // REQUIRED, Harbor folder to store image


/** Git information **/
env.gitTokenSecret = ""                                     // REQUIRED, Secret token credential stored on Jenkin, give in secretID
env.stagingBranch = ""                                      // OPTIONAL, Staging branch won't trigger merge build pipeline


/** Sonar config **/
env.maximumAllowedBugs = 0
env.maximumAllowedVunerabilities = 0
env.maximumAllowedCodeSmell = 0


/** Build prefix for building report **/
env.pushBuildPrefix = "JENKINS-PUSH"
env.mrBuildPrefix = "JENKINS-MERGE"
env.acceptCloseMRBuildPrefix = "JENKINS-ACCEPT-CLOSE"

Feature: Dynamic Environment

VTS KIT provides ability to use environment from container. All system environment which are started with VTS_KIT_ will be collected and injected into Web Server on running. Developer can reference to these environment inside window.env.

Ways to make changes to environments:

• 1. Add environment inside kubernetes YAML deployment
• 2. Use kubectl to change environment while application is running (require rolloul restart)
• 3. Set environment on running docker (if deploy as docker)

1. Add environment inside kubernetes YAML deployment:

For example, make change to development profile, create two environemnt VTS_KIT_ENV1 and VTS_KIT_ENV2. You can find kubernetes YAML under cicd/manifests/dev-deploy-manifest.yaml.

---
apiVersion: v1
kind: Service
metadata:
  name: {{appName}}-svc
  labels:
    app: {{appName}}
  namespace: {{devNamespace}}
spec:
  type: NodePort
  ports:
    - port: {{devPort}}
      name: {{appName}}-external-port
      protocol: TCP
      targetPort: {{devTargetPort}}
      nodePort: {{devNodePort}}
  selector:
    app: {{appName}}
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: {{appName}}-deployment
  labels:
    app: {{appName}}
  namespace: {{devNamespace}}
spec:
  replicas: 1
  selector:
    matchLabels:
      app: {{appName}}
  template:
    metadata:
      labels:
        app: {{appName}}
    spec:
      containers:
        - name: {{appName}}-container
          image: {{imageName}}
          env:
            - name: VTS_KIT_ENV1
              value: "Hello"
            - name: VTS_KIT_ENV2
              value: "World"
          imagePullPolicy: IfNotPresent
          ports:
            - containerPort: {{devTargetPort}}
      imagePullSecrets:
        - name: {{devImagePullSecrets}}

2. Use kubectl to change environment while application is running (require rolloul restart)

Use kubectl CLI to make change to an applied-deployment.

  // Set new environemtn
  kubectl set env deployment/demo VTS_KIT_ENV1=hello

  // Rollout restart to apply change
  kubectl rollout restart deployment/demo

  // Unset environment (Also need to rollout restart to apply change)
  kubectl set env deployment/demo VTS_KIT_ENV1-

3. Set environment on running docker (if deploy as docker)

Use docker CLI to set environment on running an image

  docker run -e VTS_KIT_ENV1=hello -t webapp-demo:1.0.0

Feature: 3rd party integration

VTS KIT offers libraries that facilitate the integration of third-party libraries and services with minimal effort.

Check out documentation for more detail.

References

• Nx Introduction
• App and lib
• Monorepo
• Buildable and Publishable

Contribute Guidelines

If you have any ideas, just open an issue and tell us what you think.

If you'd like to contribute, please refer Contributors Guide

License

This code is under the MIT License.

See the LICENSE file for required notices and attributions.