Upgrade-library-improvements

.github/workflows/npm_build.yml

@@ -39,12 +39,54 @@ jobs:
       - name: Build library
         run: yarn build
 
+      - name: Validate export targets exist
+        run: yarn check:exports
+
+      - name: Validate npm pack publish shape
+        run: yarn check:pack-shape
+
+      - name: Smoke test package exports (ESM)
+        run: yarn check:exports:esm
+
       - name: Analyze with SonarCloud
         if: ${{ github.actor != 'dependabot[bot]' }}
         uses: SonarSource/sonarqube-scan-action@v7.0.0
         env:
           SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}
 
+  node18-compat:
+    name: Node 18 Compatibility
+    if: github.event_name != 'release'
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v6
+
+      - name: Setup Node.js (18)
+        uses: actions/setup-node@v6
+        with:
+          node-version: '18.x'
+
+      - name: Enable Corepack
+        run: |
+          corepack enable
+          corepack prepare yarn@4.12.0 --activate
+
+      - name: Install dependencies
+        run: yarn install --frozen-lockfile
+
+      - name: Build library
+        run: yarn build
+
+      - name: Validate export targets exist
+        run: yarn check:exports
+
+      - name: Validate npm pack publish shape
+        run: yarn check:pack-shape
+
+      - name: Smoke test package exports (ESM)
+        run: yarn check:exports:esm
+
   release:
     name: Release and Publish
     if: github.event_name == 'release'
@@ -56,11 +98,24 @@ jobs:
       - name: Checkout repository (Release)
         uses: actions/checkout@v6
         with:
-          ref: ${{ github.event.release.target_commitish }}
+          ref: refs/tags/${{ github.event.release.tag_name }}
+
+      - name: Validate release tag matches package version
+        env:
+          RELEASE_TAG: ${{ github.event.release.tag_name }}
+        run: |
+          node - <<'NODE'
+          const fs = require('node:fs');
 
-      - name: Validate and extract release information
-        id: release
-        uses: manovotny/github-releases-for-automated-package-publishing-action@v2.0.1
+          const pkg = JSON.parse(fs.readFileSync('./package.json', 'utf-8'));
+          const tag = process.env.RELEASE_TAG || '';
+          const normalizedTag = tag.startsWith('v') ? tag.slice(1) : tag;
+
+          if (normalizedTag !== pkg.version) {
+            console.error(`Release tag (${tag}) does not match package.json version (${pkg.version}).`);
+            process.exit(1);
+          }
+          NODE
 
       - name: Setup Node.js (Release)
         uses: actions/setup-node@v6
@@ -84,8 +139,16 @@ jobs:
       - name: Build library (Release)
         run: yarn build
 
+      - name: Validate export targets exist (Release)
+        run: yarn check:exports
+
+      - name: Validate npm pack publish shape (Release)
+        run: yarn check:pack-shape
+
+      - name: Smoke test package exports (ESM) (Release)
+        run: yarn check:exports:esm
+
       - name: Publish version (OIDC via npm)
-        working-directory: dist
         run: |
           # Ensure we do NOT publish using token-based auth (classic/granular).
           unset NODE_AUTH_TOKEN

.gitignore

@@ -67,4 +67,7 @@ multi-reporter-config.json
 # Yarn audit working files
 yarn-known-issues-current
 current-ids.json
-known-ids.json
+known-ids.json
+
+# npm pack artifacts
+*.tgz

CHANGELOG.md

@@ -0,0 +1,17 @@
+# Changelog
+
+All notable changes to this package should be documented in this file.
+
+The format is based on Keep a Changelog and this project follows semantic versioning.
+
+## [Unreleased]
+
+### Changed
+- _Add entries here for each PR that changes public behavior, exports, or consumer configuration._
+
+## Changelog Policy
+
+- Add entries to `## [Unreleased]` for user-visible changes.
+- Move entries from `## [Unreleased]` into a versioned section during release.
+- Call out breaking changes explicitly with migration notes.
+- Mention any `package.json` `exports` changes that affect consumers.

README.md

@@ -11,6 +11,7 @@ This is a shared Node.js library containing common middleware, configurations, a
 - [Getting Started](#getting-started)
 - [Scripts](#scripts)
 - [Build Process](#build-process)
+- [Release Checklist](#release-checklist)
 - [Linting and Formatting](#linting-and-formatting)
 - [Exports](#exports)
 - [Using This Library in a Node.js Application](#using-this-library-in-a-nodejs-application)
@@ -23,7 +24,8 @@ This is a shared Node.js library containing common middleware, configurations, a
 Ensure you have the following installed:
 
 - [Node.js](https://nodejs.org/) v18 or later
-- [Yarn](https://classic.yarnpkg.com/) v1.22.22 or later
+- [Yarn](https://yarnpkg.com/) v4.x (Berry)
+- ESM-compatible consumer setup (`import` syntax). CommonJS `require()` is not supported.
 
 ### Install Dependencies
 
@@ -39,7 +41,7 @@ Run the following to build the project:
 yarn build
 ```
 
-The compiled output will be available in the `dist/` folder. It includes `index.js`, type declarations, and any exported modules listed in the `exports` field.
+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
 
@@ -56,17 +58,19 @@ To use a published version of this library during development in another project
 
 To use a local version of this library during development in another project:
 
-1. Build this library:
+1. Build and pack this library:
 
    ```bash
-   yarn build
+   yarn pack:local
    ```
 
-2. In your consuming project (e.g. `opal-frontend`), ensure you have set an environment variable pointing to the local build:
+   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/`):
 
    ```bash
    # In your shell config file (.zshrc, .bash_profile, or .bashrc)
-   export COMMON_NODE_LIB_PATH="[INSERT PATH TO COMMON NODE LIB DIST FOLDER]"
+   export COMMON_NODE_LIB_PATH="[INSERT PATH TO COMMON NODE LIB REPOSITORY ROOT]"
    ```
 
 3. In the consuming project (e.g. `opal-frontend`), run:
@@ -75,9 +79,10 @@ To use a local version of this library during development in another project:
    yarn import:local:common-node-lib
    ```
 
-   This will remove the published version and install the local build using the path provided.
+   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:
+
    ```bash
    yarn import:published:common-node-lib
    ```
@@ -99,6 +104,22 @@ After this new version of the library is published, any consuming application sh
     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:
+
+   ```bash
+   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:
@@ -157,7 +178,10 @@ Refer to the `exports` block in `package.json` for the full list of available mo
 The following commands are available in the `package.json`:
 
 - `yarn build`  
-  Cleans the `dist/` folder, compiles TypeScript, and copies relevant files to `dist/`.
+  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.