General

This project wraps the backend APIs used by NG-UI and custom projects.

It is published as @deviceinsight/ng-ui-api-client. The package is ESM-first (dist/index.js) with a CommonJS build (dist/index.cjs) and type declarations (dist/types/index.d.ts). axios is a peer dependency and has to be provided by the consuming project.

Every module under src covers one backend resource (e.g. asset.ts, event.ts, user.ts, role.ts, licenses.ts) and is re-exported from src/index.ts. src/axios.ts holds the shared axios instance; it exports getAxios, setAxios and setAxiosConfig, which the consuming application uses to inject its configured axios client.

Development

Node is pinned via .nvmrc (see also the engines field in package.json).

npm install

Available scripts:

| Script | Description | | ------------------- | ---------------------------------------------------------------------- | | npm run build | Cleans dist, bundles with Vite and emits types via tsconfig.types.json | | npm run watch | tsc --watch | | npm run clean | Removes dist | | npm run typecheck | tsc --noEmit | | npm run lint | Lints src with oxlint and checks formatting (npm run lint:fix to autofix) | | npm run prettier | Formats the TypeScript sources | | npm run scan | Vulnerability scan via audit-ci using scan-config.json5 |

There are no unit tests in this project.

Commits are checked by a husky pre-commit hook that runs lint-staged (prettier on the staged TypeScript files).

CHANGELOG.md is maintained per version under the version of package.json without -SNAPSHOT. Renovate dependency updates append their entry automatically via the postUpgradeTasks hook in renovate.json, which calls ./update-changelog.sh <depName> <currentVersion> <newVersion>; patch updates are skipped. All other changes have to be added to CHANGELOG.md by hand in the same merge request.

Linking for local development

We recommend using the yalc tool for linking @deviceinsight/ng-ui-api-client. It's because yalc generates exactly the same package as it would be published to the npm registry, especially it removes files that should be ignored and their existence cause problems when we use npm link.

Here's how to do the linking:

npm run build
npx yalc publish

# in the project where you want to link this library to:
npx yalc link "@deviceinsight/ng-ui-api-client"

CI

.gitlab-ci.yml installs the dependencies and then runs lint and typecheck on every branch except main. The audit job (npm run scan) only runs on develop, feature/* and renovate/* branches, so hotfixes and tags are not blocked by it. The publish job runs for develop and for tags: -SNAPSHOT versions are published to the internal Nexus registry under the next tag, releases go to the public npm registry. A release older than the currently published latest is published under a hotfix-<major>.<minor> tag so that latest is not moved backwards. publish_alpha is a manual job that always publishes to the internal registry under next.

Releasing the library using git flow

Prerequisites

git flow

The git flow tools need to be installed. This depends on your operating system.

They can be also installed from the git repo: https://github.com/petervanderdoes/gitflow-avh

After git flow is installed, the repo needs to be initialized. Make sure that the main branch is locally available. If not, execute git checkout main. Run git flow init and answer every question with the default (press Enter/Return). The script verifies that the branches are named main and develop.

Releasing the develop branch

Run the release script from the repository root:

./release.sh

Before running it, make sure the workarea is clean and all commits on develop are pushed; otherwise the script aborts. It releases the current version from package.json (without -SNAPSHOT) and afterwards starts the next minor snapshot version.

Building a hotfix for a specific version of this library

When building a hotfix in ng-ui-scale, first check which version of this library is used on the main branch of ng-ui-scale, e.g. with git show origin/main:package.json | grep ng-ui-api-client. Then build the hotfix on top of exactly that version, so that no unrelated changes from newer releases end up in the ng-ui-scale hotfix. Do not use release.sh or git flow hotfix for this: git flow hotfix finish merges into main, which already contains the newer release.

Example: ng-ui-scale uses 10.56.0 while 10.57.0 is already released (the version on main of this library):

1. Create the branch hotfix/10.56.1 from the tag 10.56.0 and install the dependencies of that version:

   git fetch --tags
   git checkout -b hotfix/10.56.1 10.56.0
   npm ci

2. Set the version in package.json and package-lock.json to 10.56.1:

   npm version 10.56.1 --no-git-tag-version

   If the audit job in .gitlab-ci.yml still runs on every branch except main, copy its rules from develop, so that the vulnerability audit does not block the hotfix pipeline.
3. Implement or cherry-pick the changes needed for the hotfix, either directly on the hotfix branch or in a feature branch that is merged into it.
4. Run npm run build, npm run lint and npm run typecheck to verify there are no errors.
5. Commit the changes.
6. Tag the hotfix commit and push the tag:

   git tag -a 10.56.1 -m "Hotfix 10.56.1"
   git push origin 10.56.1

   The publish CI job builds the tag and publishes it to npm. Because 10.56.1 is older than the latest version, it is published under the dist-tag hotfix-10.56 and latest stays at 10.57.0.
7. Merge the hotfix branch into develop and push develop:

   git checkout develop
   git pull
   git merge --no-ff hotfix/10.56.1
   git push

   package.json and package-lock.json will conflict; keep the -SNAPSHOT version of develop and run npm install before committing the merge. Do not merge the hotfix branch into main.
8. Delete the local hotfix branch: git branch -d hotfix/10.56.1.
9. Update ng-ui-scale on its hotfix branch to 10.56.1.