sushublib v0.0.0

Sustainability Hub Shared Components Library

This document will guide you on how to update and use this shared custom angular library. Shared content from this library can be consumed by the buyer and supplier front-end repositories.

Contents

• 1 Project structure
• 2 Customizing
• 3 Testing
• 4 Building
• 5 Using the library
• 6 What it is important to know

1 Project structure

• Projects

  • package.json: Npm options for workspace for the library
  • ng-package.json: Angular packager options
  • tsconfig.base.json: Ngc compiler options for AoT compilation
  • package.json: Npm options for workspace for the Workspace

• projects/sustainability-shared-components

  • src/lib: Directory for creating the classes
  • public_api.ts: Entry point for all public APIs of the package
  • package.json: Npm options for library
  • src/lib/sustainability-shared-components.module.ts: Define declarations, imports, exports and providers for your library

• projects/libtest: Directory for consuming test application

• dist/sustainability-shared-components: Directory for compiled library code
• dist/libtest: Directory for test application compiled code

2 Customizing

• Creating Components: All shared components should be created within the lib/components folder of the Sustainability Shared Components library. Each component should be encapsulated in its own folder, with the template, styles, scripts and all services specific to that component all enclosed in an appropriately named sub-directory.
• Creating Services: Services that are intended to be used by more than one component within the library should be created within the lib/services folder. Each service and it's related files should be encapsulated within it's ownself-descriptive sub-directory.
• Models, Interceptors & Utilities: Models, Interceptors and Utilities such as pipes all have their respective directories within the lib folder. All files created should be stored within their appropriate directories.
• Using the Sustainability Shared Components Module file: To ensure all created components and services are available for use and recognized as a part of the library all components must be declared and exported, Relevant services should also be included in the providers, while imported modules or 3rd part libraries are declared in the providers array (please ensure all 3rd party libraries are also listed as peer dependencies in the package .json file).
• Defining the entry points: To expose the functionality of our library to the consuming application, all created components must be listed within the public-api. ts file. This file allows the export of all relevant classes in the following format:

export <class|*> from <path>

3 Testing

The following command runs unit & integration tests that are in the tests folder (you can change the folder in spec.bundle.js file):

npm test

or in watch mode:

npm run test:watch

4 Building

If you have made any changes to the library (e.g. updated a class or function), update the library version (Semantic Versioning) in the sustainability-shared-components package.json file.

Then run the following command:

npm run susbuild

• starts TSLint with Codelyzer using Angular TSLint Preset
• starts AoT compilation using ngc compiler
• creates dist folder with all the files of distribution, following Angular Package Format (APF):

└── dist
    ├── bundles
    |   ├── sustainability-shared-components.umd.js
    |   ├── sustainability-shared-components.umd.js.map
    |   ├── sustainability-shared-components.umd.min.js
    |   └── sustainability-shared-components.umd.min.js.map
    ├── esm5
    |   ├── **/*.js
    |   └── **/*.js.map
    ├── esm2015
    |   ├── **/*.js
    |   └── **/*.js.map
    ├── fesm5
    |   ├── sustainability-shared-components.js
    |   └── sustainability-shared-components.js.map
    ├── fesm2015
    |   ├── sustainability-shared-components.js
    |   └── sustainability-shared-components.js.map
    ├── lib
    |   └── **/*.d.ts
    ├── sustainability-shared-components.d.ts
    ├── sustainability-shared-components.metadata.json
    ├── LICENSE
    ├── package.json
    ├── public_api.d.ts
    └── README

To create the npm package:

cd dist/sustainability-shared-components

npm pack

npm pack reads the version from your package.json file and will generates a .tgz file (sustainability-shared-components-{version}.tgz) in the dist/sustainability-shared-components directory.

Then you can install it in libtest app to test it:

cd ../..

npm install ./dist/sustainability-shared-components/sustainability-shared-components-{version}.tgz

ng build libtest

ng serve

5 Using the library in consuming application

Installing

For now requires the --force flag. Fix for this is required.

npm install [path]sustainability-shared-components-{version}.tgz --force

6 Important to know

1. package.json

   • "main": "./bundles/angular-library-starter.umd.js" legacy module format
   • "module": "./esm5/angular-library-starter.js" flat ES module, for using module bundlers such as Rollup or webpack
   • "es2015": "./esm2015/angular-library-starter.js" ES2015 flat ESM format
   • "typings" declaration files for TypeScript compiler
   • "peerDependencies" the packages and their versions required by the library when it will be installed

2. tsconfig.json file used by TypeScript compiler

   • Compiler options:
     • "strict": true enables TypeScript strict master option

3. tsconfig-build.json file used by ngc compiler

   • Compiler options:

     • "declaration": true to emit TypeScript declaration files
     • "module": "es2015" & "target": "es2015" are used by Rollup to create the ES2015 bundle

   • Angular Compiler Options:

     • "enableResourceInlining": true inlining of templates & styles
     • "skipTemplateCodegen": true skips generating AoT files
     • "strictMetadataEmit": true without emitting metadata files, the library will not be compatible with AoT compilation: it is intended to report syntax errors immediately rather than produce a .metadata.json file with errors
     • "flatModuleId": "@scope/package" full package name has to include scope as well, otherwise AOT compilation will fail in the consumed application
     • "enableIvy": false libraries don't need to enable Ivy

4. rollup.config.js file used by Rollup

   • format: 'umd' the Universal Module Definition pattern is used by Angular for its bundles
   • moduleName: 'ng.angularLibraryStarter' defines the global namespace used by JavaScript apps
   • external & globals declare the external packages

5. Server Side Rendering

   If you want the library will be compatible with Server Side Rendering:

   • window, document, navigator and other browser types do not exist on the server
   • don't manipulate the nativeElement directly