HMPPS Electronic Monitoring Components

Reusable web components and map utilities for Electronic Monitoring UI applications.

Documentation

Component usage, demos, and API reference are available in Docs:

View the documentation site

Documentation & Preview Sites (GitHub Actions)

Every branch automatically builds its own Storybook documentation preview using GitHub Actions.

• When you push a branch, Storybook is built and deployed to GitHub Pages.
• When that branch is deleted, the preview site is automatically removed.

How to check your branch preview

After pushing your branch, wait for the “Deploy Storybook (docs site)” GitHub Action to complete.
You can then access the docs at the URL:

https://ministryofjustice.github.io/hmpps-electronic-monitoring-components//

For example:

| Branch name | Docs URL | | -------------------- | ---------------------------------------------------------------------------------------------- | | main | https://ministryofjustice.github.io/hmpps-electronic-monitoring-components/ | | new-feature | https://ministryofjustice.github.io/hmpps-electronic-monitoring-components/new-feature/ | | feature/new-map-ui | https://ministryofjustice.github.io/hmpps-electronic-monitoring-components/feature-new-map-ui/ |

When you delete a branch, the workflow automatically cleans up the corresponding preview directory from GitHub Pages.

Development Setup

npm install

Live test components in Local development

Start the feature development environment:

npm run start-feature

Testing

Unit tests (Jest)

npm test

Run in CI mode:

npm run test:ci

Integration tests (Cypress)

Component-level integration tests use Cypress Component Testing.

Run headless:

npm run int-test

Run with UI (Chrome):

npm run int-test:ui

Publishing to npm

Publishing is now fully automated through GitHub Actions when changes are merged into the main branch.

What happens automatically

When a pull request is merged into main, the pipeline will:

1. Run linting, type checking, unit tests, and integration tests.
2. Build the library.
3. Check if the version in package.json has changed.
   • If it has changed, a Git tag is automatically created (e.g. v0.0.7).
   • If it has not changed, the workflow fails - reminding the developer to bump the version before merging.
4. The new tag automatically triggers the Publish package workflow, which:
   • Rebuilds the package.
   • Publishes it to npm using OpenID Connect (OIDC) authentication - no manual login or tokens required.

To prepare a branch for release

Before creating a PR:

• Manually bump the version in package.json using semantic versioning:

  npm version patch   # for bug fixes
  npm version minor   # for backward-compatible features
  npm version major   # for breaking changes

• Commit and push the updated package.json to the feature branch.

When the PR is merged into main, the CI/CD workflow will handle tagging and publishing automatically.

📦 npm package

Once published, the latest version of the package will be available on npm:

@ministryofjustice/hmpps-electronic-monitoring-components

You can view it on npmjs.com

Summary

| Action | Trigger | Output | | ------------------- | -------------------------------- | ------------------------------------------------------ | | Build & Test | Any branch push / PR | Validates code (lint, types, unit + integration tests) | | Docs Preview | Any branch push | Deploys Storybook preview for the branch | | Docs Publish | Merge to main | Updates documentation on GitHub Pages | | Version & Tag | Merge to main with new version | Creates Git tag (vX.Y.Z) | | Package Publish | Tag (auto or manual) | Publishes new npm package version |