This package contains the Open Water Foundation (OWF) Angular common library, which is used to develop common library code in the AngularDev workspace. It can then be used by other Angular applications such as OWF InfoMapper.

• Building the Common Library
• Publishing the Common Library
• Setting up a Library to use GitHub Packages
• Changelog
• Running Unit Tests
• Code Scaffolding
• Further Help
• Troubleshooting

See the following resources for background information for the library.

• Publishing private npm packages using GitHub Packages.
• Configuring npm for use with GitHub Packages.
• Semantic Versioning.

From the ng-workspace folder, type ../build-util/create-common-package.sh to build the project through Angular and create a tarball file through npm. This allows the library to be published using the created distributable version of the library in the dist/ folder, or by installing the local tarball file in another local application's package.json dependencies. This is used for testing the library.

To publish as a GitHub Package using npm, perform the following steps:

Note: If publishing the package for the first time, skipping to step 3 will publish the package as the default version of 0.0.1.

1. cd into ng-workspace/projects/OpenWaterFoundation/common

2. npm version <version_number> where <version_number> is the new version to be published. If a version of the library has already been published, the version number must be incremented. Using GitHub semantic versioning is highly advised. In-depth information can be found at the semver GitHub account.

3. Follow the instructions under Building the Common Library above.

4. cd into the dist/OpenWaterFoundation/common folder.

5. Authenticate to GitHub Packages/npm by logging in to the GitHub Packages registry by using the command:

   npm login --registry=https://npm.pkg.github.com --scope=OWNER
   

   replacing OWNER with the owner of the repository - OpenWaterFoundation in this case. Three prompts will display:

   • Username - GitHub username. This must be all lower case or it will ask again.
   • Password - GitHub account personal access token with repo and read:packages access permissions.
   • Email - GitHub email address.

   A successful login will show something similar to

     Logged in as <User> to scope @OpenWaterFoundation on https://npm.pkg.github.com/.
   

6. npm publish to publish the package using GitHub packages. More information can be found at Setting up a Library to use GitHub Packages.

The following sections include authenticating and publishing to GitHub packages, and the installing of GitHub packages in an application. This section is mostly for developers, and can be largely skipped if only the installation and utilization of the common library is needed. To use the library, follow number 4 under Installing a GitHub Package.

The .npmrc file can be used to configure the scope mapping for the project, and prevents other developers from accidentally publishing the package to npmjs.org instead of GitHub Packages. Publish the package as follows:

1. Authenticate to GitHub Packages. This is done in Authenticating to GitHub Packages above.
2. Add registry=https://npm.pkg.github.com/OWNER in the .npmrc file, replacing OWNER with the name of the user or organization that own the repository containing the project.
3. Add the .npmrc file to the repository via git push.
4. GitHub Package set up is now complete. Publish the package by following the instructions in Publishing the Common Library.

The following instructions are for setting up an already existing application to be able to communicate with GitHub so that an npm created GitHub Package can be consumed:

1. In the same directory as the app package.json file, create or edit an .npmrc file and add

   @OWNER:registry=https://npm.pkg.github.com
   

   replacing OWNER with the name of the user or organization account that own the repository containing the project.
2. Add the .npmrc file to the repo the application belongs to so GitHub Packages can find the project.
3. Configure the package.json to use the package being installed. This means adding it to the dependencies. This needs to be done manually by a developer, then once there, it will be in the repository and used when cloned/fetched/pulled. For example, the dependencies property would look something like:

   {
     "name": "@my-org/my-app",
     "version": "1.0.0",
     "description": "An app that uses the @openwaterfoundation/common package",
     "main": "index.js",
     "author": "",
     "license": "MIT",
     "dependencies": {
       "@OpenWaterFoundation/common": "0.0.1-alpha.6"
     }
   }

4. The package can now be installed by typing npm install like any other npm package.

To install the dependencies of a project using GitHub Packages from a git clone, perform the following steps (assuming InfoMapper is being used):

1. cd into the directory that will hold the repository folder.
2. git clone [email protected]:OpenWaterFoundation/owf-app-infomapper-ng.git
3. cd owf-app-infomapper-ng/infomapper
4. Follow step 5 under Publishing the Common Library
5. Run npm install

See the Common library Changelog.

From anywhere in the Angular project, run ng test @OpenWaterFoundation/common to execute the unit tests via Karma.

Run ng generate component component-name --project common to generate a new component. You can also use ng generate directive|pipe|service|class|guard|interface|enum|module --project common.

Note: Don't forget to add --project common or else it will be added to the default project in your angular.json file.

The common library uses some helper classes that use static methods. Angular libraries will run into a metadata error if these classes are used. The only solution is to "suppress" the error by adding the line

// @dynamic

right above the class declaration. The error will be stopped, and the library can be built.

To get more help on the Angular CLI use ng help or go check out the Angular CLI README.

For more information on how this library is used, go to the AngularDev README

This section aims to help alleviate any issues caused by updates, authenticating, and other necessary actions to use, create, and/or publish the OWF Common Library.