@opengeoweb/airmet v1.0.18

Opengeoweb

Nx workspace for geoweb products. This project was generated using Nx. This workspace contains the following products:

• knmi-geoweb: React frontend application (apps/knmi-geoweb)
• sigmet: React component library (libs/sigmet)

Installation

To run the opengeoweb commands you need both NPM and Nx. The easiest way to install NPM is via nvm. Please visit https://nvm.sh/ and follow the instructions. When nvm is installed, run the following commands to install NPM and Nx:

nvm install 12
npm install -g nx
npm ci

Running the application

Run nx serve or npm run start to start the default application, which is knmi-geoweb.

Running browser tests

To run all the cypress tests locally (automatically starts up the knmi-geoweb application):

nx e2e knmi-geoweb-e2e

To keep the Cypress GUI open, add the watch flag: nx e2e knmi-geoweb-e2e --watch.

Running storybook

nx run form-fields:storybook
nx run sigmet:storybook
nx run spaceweather:storybook
nx run taf:storybook
nx run shared:storybook

Running unit tests

Run nx test <lib-name> to execute the unit tests for a single library.

Run npm run test:all to execute the unit tests from all libraries affected by a change.

Run nx test <lib-name> --test-file <file-pattern> to execute a specific unit test

Generating a new React component in an existing app or lib

For example, run nx g @nrwl/react:component my-component --project=sigmet to generate a new component inside the sigmet library.

Updating packages

To update all Nx packages (@nrwl):

1. run npm run update
2. follow the instructions!
3. commit and merge the changes

To update other packages:

1. to see a list of which packages could need updating, run npm outdated -l
2. check if there are any breaking changes to be aware of in the new version of a package
3. update a single package: npm install <package-name>@<version> or npm install <package-name>@<version> --save-dev
4. commit the updated files package.json and package-lock.json
5. update the code related to changes if needed
6. commit and merge the changes

Installing new dependencies

Installing new dependencies works the same as every project: npm install <package-name>@<version> or npm install <package-name>@<version> --save-dev

When working on a library, make sure you include the dependency to build task, under the key external. Example:

"projects": {
    "sigmet": {
      "projectType": "library",
      "architect": {
        "build": {
          "builder": "@nrwl/web:package",
          "options": {
            "external": ["react", "react-dom", "@material-ui/core", "@material-ui/icons"],
          }
        },
    }
}

When using the library, for example "@material-ui/icons", always import like this:

import { Create } from "@material-ui/icons"

DON'T do this, it will cause a build error:

// this will break the build
import Create from "@material-ui/icons/create"

Bundling, packaging and publishing to NPM

We use Semantic Versioning, see the documentation for details.

1. Decide how to bump the version, is it a major, minor or patch version?
2. Create a new branch based off master
3. Make sure there is an upstream branch (check with git push)
4. Make sure your local git tags are in sync with the remote (check with git tag). If you have local tags that are not on the remote, remove them with git tag -d tagname.
5. Update the version by running npm version major|minor|patch
6. The changes are committed and pushed automatically. Get the branch merged into master.
7. The release tag was created and pushed automatically. Make sure to add a description of changes in the Release notes for the tag.
8. Go to the gitlab pipeline of master and run the publish job for any affected libraries
9. The libraries will be published to the @opengeoweb organisation on npmjs.

Generating a dependency graph

Run nx affected:dep-graph to see a diagram of the dependencies of your projects. Note that it doesn't automatically update on changes. To see your changes reflected in the graph, rerun the command.

Documentation

It is possible to automatically generate documentation from the source code using TypeDoc.

In order to do so, run nx run <project-name>:docs.

Please note that nothing will be created if the code contains errors. Otherwise, a new docs/<project-name> folder will be created under the root folder.

Documentation is also published from the gitlab pipeline of master and can be found here:

• Sigmet
• Taf
• Spaceweather
• Airmet

Adding an application to this workspace

Run nx g @nrwl/react:app my-app to generate an application.

When using Nx, you can create multiple applications and libraries in the same workspace.

Adding a new library to this workspace

Libraries are shareable across other libraries and applications. They can be imported from @opengeoweb/mylib.

1. Run nx g @nrwl/react:lib <name> to generate a react library. Run nx g @nrwl/react:lib <name> --publishable --importPath="@opengeoweb/<name>" to generate a react library that can be published to npm.
2. Configure storybook by running nx g @nrwl/react:storybook-configuration <name>. Make sure it uses a unique port, you can configure this in workspace.json. Compare the contents of the .storybook folder with one of the other libraries and copy/update the files to be similar.
3. Make sure to update the sync-version script in package.json, this will keep the versions synchronized automatically. If you made a non-publishable library, you have to manually add the package.json file.
4. Tag the project in nx.json. These tags provide constraints on importing as defined in .eslintrc.json. For more info see Nx tags. To see changes in tags take effect, you have to reopen VSCode.
5. Add the necessary custom scripts in workspace.json: typecheck | docs.
6. Make sure tsconfig.lib.json does not exclude stories or tests, and has the necessary types (copy from another lib). And make sure the typecheck script in the workspace file points to this tsconfig.lib.json.
7. Update the test script in workspace.json to use the setupFile and include coverage (copy from one of the other test scripts).
8. Update the eslintrc.json, copy the contents from one of the other libs.
9. Make sure the pipeline jobs include the new library where needed, at least create a new job to run the tests.
10. If you run into the error Buildable libraries cannot import non-buildable libraries, add a build script for your new library in workspace.json.

Removing a project from this workspace

Run nx g @nrwl/workspace:remove <name>.

Further help

Visit the Nx Documentation to learn more.

Custom build scripts

Custom scripts are currently defined in two places; in workspace.json and package.json. Tasks need to be defined in workspace, and be used via npm script. We're currently investigating if this is the way to go (Nx builders vs Nx schematics), so it might change in the future. Current tasks (as defined in workspace.json):

To run a command for a specific app or library: nx typecheck sigmet

To use these commands with the affected: nx affected --target=typecheck

For now the 'global' scripts are prefixed with geoweb, and the project specific with sigmet. We use these prefixes to differentiate default scripts with our custom ones.

geoweb:typecheck

Typechecks the TS code

geoweb:docs

Generates documentation from the source code using TypeDoc.

Licence

This project is licensed under the terms of the Apache 2.0 licence. Every file in this project has a header that specifies the licence and copyright. It is possible to check/add/remove the licence header using the following commands:

npm run licence:check => checks all the files for having the header text as specified in the LICENCE file. The format and which files to include is specified in licence.config.json.

npm run licence:add => adds licence to files without it. This action can require a manual check when the file contains a wrong header (i.g. a simple word is missed), because it just adds another header without removing the wrong one.

npm run licence:remove => removes licence from all files. This action can require a manual check when the file contains a wrong header (i.g. a simple word is missed), because it only removes a correct header and not a wrong one.

Code linting

The code is linted by Eslint. All projects/libraries currently use the same configuration file: .eslintrc, located in the root of the project. If you need more or less rules for the whole project, edit this file. If you need specific rules for a app/lib (when you don't use React for example) then you can edit the .eslintrc file in the app/lib root folder.

lint workspace

npm run lint

lint affected project

npm run affected:lint

lint specific app/lib

nx lint sigmet or nx run sigmet:lint

Build and configure a bundle for the KNMI GeoWeb frontend

After checking out the correct tag from this repository and running npm ci, a bundle for the KNMI geoweb frontend can be generated with the following command:

rm -rf dist && npm run knmi-geoweb:build

The knmi-geoweb frontend will be written to the ./dist/apps/knmi-geoweb folder.

This folder can be hosted from a bucket or tested out locally using npx serve -p 4200 -s dist/apps/knmi-geoweb

The configuration file of the frontend is in knmi-geoweb/assets/config.json. This configuration file should be genereated and written by CI/CD. The configuration file is a json with the following properties:

{
  "AUTH_LOGIN_URL": "https://??????/authorize?client_id=???&response_type=code&scope=email+openid&redirect_uri=???/code",
	"AUTH_LOGOUT_URL":   "AUTH_LOGOUT_URL": "https://??????/logout?client_id=???&logout_uri=???/login",
	"AUTH_TOKEN_URL": "https://??????/token",
	"AUTH_CLIENT_ID": "someid",
	"APP_URL": "https://??????",
	"INFRA_BASE_URL": "https://??????/infra",
	"SW_BASE_URL": "https://??????/spaceweather",
	"SIGMET_BASE_URL": "https://??????/aviation",
	"TAF_BASE_URL": "https://??????/aviation"
}