OPAL Frontend Common Node Library

This is a shared Node.js library containing common middleware, configurations, and utilities used across OPAL backend services.

Table of Contents

• Getting Started
• Scripts
• Build Process
• Release Checklist
• Linting and Formatting
• Exports
• Using This Library in a Node.js Application
• Switching Between Local and Published Versions

Getting Started

Prerequisites

Ensure you have the following installed:

• Node.js v18 or later
• Yarn v4.x (Berry)
• ESM-compatible consumer setup (import syntax). CommonJS require() is not supported.

Install Dependencies

yarn

Build Process

Run the following to build the project:

yarn build

The compiled output will be available in the dist/ folder. It includes runtime JavaScript and generated type declarations based on the TypeScript build configuration.

Switching Between Local and Published Versions

See opal-frontend for how this library is consumed in practice.

Use the yarn import:local:common-node-lib and yarn import:published:common-node-lib scripts in your consuming project (opal-frontend) to switch between local development and the published npm version of the library.

To use a published version of this library during development in another project:

1. In the consuming project, run:

   yarn import:published:common-node-lib

To use a local version of this library during development in another project:

1. Build and pack this library:

   yarn pack:local

   This will generate a .tgz file (e.g. hmcts-opal-frontend-common-node-X.Y.Z.tgz) in the repository root.

2. In your consuming project (e.g. opal-frontend), ensure you have set an environment variable pointing to this library repository root (not dist/):

   # In your shell config file (.zshrc, .bash_profile, or .bashrc)
   export COMMON_NODE_LIB_PATH="[INSERT PATH TO COMMON NODE LIB REPOSITORY ROOT]"

3. In the consuming project (e.g. opal-frontend), run:

   yarn import:local:common-node-lib

   This will remove the currently installed version and install the locally packed .tgz artifact. Installing the tarball (rather than linking the repository folder directly) ensures the consuming project uses the same publish shape as npm, avoiding TypeScript and export-map resolution issues.

4. To switch back to the published version:

   yarn import:published:common-node-lib

This setup makes it easy to switch between development and production versions of the shared library.

Publish the library

Once any changes have been approved and merged into the main branch, you'll need to publish a new version of the library so that it can be consumed by other projects. To do this:

1. Increment the version number in both the library's root package.json.
2. Commit and push those changes to the main branch.
3. On GitHub, create a new release and use the updated version number as a tag.
4. When the release workflow completes, the library will be published.

After this new version of the library is published, any consuming application should remove the local or outdated version of the library and then install the published version by running:

```bash
yarn import:published:common-node-lib
```

Release Checklist

Before creating a GitHub release tag:

1. Update package.json version to the intended release version.

2. Add a CHANGELOG.md entry under ## [Unreleased] describing user-visible changes.

3. Run:

   yarn build
   npm pack --dry-run

4. Ensure export map changes are intentional and non-breaking (or include release notes/version bump for breaking changes).

5. Create a GitHub release with a tag matching package.json version (vX.Y.Z or X.Y.Z).

Linting and Formatting

To lint and check formatting:

yarn lint

There is a custom lint rule for member ordering to ensure members in the code are ordered in the following format:

[
  "private-static-field",
  "protected-static-field",
  "public-static-field",
  "private-instance-field",
  "protected-instance-field",
  "public-instance-field",
  "constructor",
  "private-static-method",
  "protected-static-method",
  "public-static-method",
  "private-instance-method",
  "protected-instance-method",
  "public-instance-method"
]

To fix formatting issues automatically:

yarn prettier:fix

Exports

This library exposes multiple entry points under the exports field of package.json. Example usage:

import { CSRFToken } from '@hmcts/opal-frontend-common-node/csrf-token';
import { AppInsights } from '@hmcts/opal-frontend-common-node/app-insights';
import { Helmet } from '@hmcts/opal-frontend-common-node/helmet';
import { LaunchDarkly } from '@hmcts/opal-frontend-common-node/launch-darkly';
import {
  ExpiryConfiguration,
  RoutesConfiguration,
  SessionStorageConfiguration,
  TransferServerState,
} from '@hmcts/opal-frontend-common-node/interfaces';

Refer to the exports block in package.json for the full list of available modules.

Commonly Used Commands

The following commands are available in the package.json:

• yarn build
  Cleans the dist/ folder and compiles TypeScript into the publishable dist/ output.

• yarn pack:local
  Builds the project (via the prepack hook), removes old local tarballs, and creates a fresh .tgz package that mirrors the published npm artifact. Useful for testing changes in a consuming application.

• yarn clean
  Removes the dist/ directory.

• yarn lint
  Runs ESLint across the src/ directory and checks formatting using Prettier.

• yarn prettier
  Checks if files are formatted correctly.

• yarn prettier:fix
  Automatically formats the codebase.