NGX-PFE Developer Documentation

• 1. Documentation/Viewer
• 2. Building
• 3. Release Process
  • 3.1. Create Releases
  • 3.2. How Does the Release Process Work
  • 3.3. Building the Documentation
• 4. Debugging
  • 4.1. Troubleshooting
• 5. Deployment
  • 5.1. Clarity

The documentation in this section is intended for developers that work on the pfe itself.

Development

If you want to contribute, you might be interested in the following information.

1. Documentation/Viewer

To access the documentation - which is the basis to contribute to this library - clone this project and run the following commands:

# Install all dependencies
npm install

# Run the viewer to access the documentation
npm start

This will start a local webserver serving the documentation which is using the integrated sources of the library. This allows you to extend the library and the documentation at the same time.

2. Building

Run the following script to build the viewer application.

npm run build

This will create deployable build in the folder dist.

Run the following script to build the library:

npm run bundle-lib

It will create the build in dist ready to be published. This is powered by ng-packagr which generates the necessary bundles to be consumed by most build systems.

3. Release Process

The PFE uses a release process which is integrated into the GDF Jenkins.

There are two different types of releases:

• Beta versions, which are automatically created after every merge to the main branch
• Stable versions, which are automatically created after manually starting a job in Jenkins

The release process itself relies on commit-and-tag-version with conventional commits to determine the version number and to generate the changelog. That means, the usage of commit messages compatible with conventional commits is mandatory.

3.1. Create Releases

How to Create a Beta Release

1. Merge to main
2. The beta release job is automatically triggered
3. The release is pushed to nexus and a tagged git commit is pushed to GitHub. These beta release commits don't update the CHANGELOG.md file.

How to Create a Stable Release

1. Run the stable release job. The release is created out of the current main state.
2. The release is pushed to nexus and a tagged git commit is pushed to GitHub. The stable releases automatically update the CHANGELOG.md file.

3.2. How Does the Release Process Work

The following graphic shows the release process:

This ticket contains more details on how the process was implemented.

3.3. Building the Documentation

The documentation can be rebuilt with the following cmd:

npm run docs

Local Development of NGX-PFE with an App that uses the NGX-PFE library

For testing/development of NGX-PFE is it often helpful to integrate it with a real application locally.

To do this, follow these steps:

• npm install
• Run the library build
• npm install -g install-local (if permission denied, tried it as superuser sudo)
• install-local ..\{your-ngx-library}\dist\lib

This approach also works for connecting ngx-xtra library with other applications.

4. Debugging

Unfortunately, the angular cli currently doesn't support source maps for code under node_modules. This makes it difficult to debug library issues that are located in the library.

The following workaround can be used for debugging: (This is suitable for all libraries, not just the pfe)

1. Delete the ngx-pfe folder from node_modules
2. Update the tsconfig.json of the app where the library is integrated. Example configuration:

  "compilerOptions": {
    "baseUrl": "./",
    "paths": {
      "@allianz/ngx-pfe": ["./ngx-pfe/library/public-api", "./src/ngx-pfe/library/public-api"],
      "@allianz/ngx-pfe/*": ["./ngx-pfe/library/public-api", "./src/ngx-pfe/library/public-api"]
    }
}

It might be, that the relative path doesn't work. Then an absolute one needs to be used. Under windows \\ might need to be used in that path.

3. Either copy the library folder or git clone the library folder to (delete everything else in the checkout folder): src/library/* or the location, where typescript is searching for the files.

See also: https://www.typescriptlang.org/docs/handbook/module-resolution.html#path-mapping

4.1. Troubleshooting

Some common issues with this approach:

InjectionToken

If this error occurs during the build:

ERROR in src\app\app.module.ts(261,16): Error during template compile of 'AppModule'
  Function calls are not supported in decorators but 'InjectionToken' was called in 'NGX_PFE_CONFIGURATION'    'NGX_PFE_CONFIGURATION' references 'NGX_PFE_CONFIGURATION'
      'NGX_PFE_CONFIGURATION' calls 'InjectionToken' at ngx-pfe\library\models\ngx-pfe-module-configuration.model.ts(4,85).

the following mapping needs to be added to the tsconfig:

"@angular/*": ["<absolute path to>\\node_modules\\@angular\\*"]

Case Sensitive Paths

The angular compile might throw a warning that the case of the mapping path differs from other references. Make sure, that the mapping path in the tsconfig matches the output of the compiler.

5. Deployment

• The viewer documentation is currently deployed [here][docs] whenever the master branch is changed.
• The library part is published every time the master branch changes.
• New releases are triggered manually.

5.1. Clarity

You will notice some dependencies of the viewer application (not the library of course) from [Clarity][clarity]. This is a UI framework like Angular Material Design or Bootstrap and supports our viewer with elements like sidebar, sourcecode component and header navigation. These are parts not available in Patternlab in this form. We are happy to use it at the moment but in the long-term we want to create a viewer fully based on ndbx styles.

The usage of the clarity framework in combination with Patternlab means that there are two CSS frameworks in one place, which caused some problems and collisions in the past. We created a custom build of clarity's css to minimize any problems.