CCM-16572: Migrating npm to pnpm

.github/actions/acceptance-tests/action.yaml

@@ -35,14 +35,20 @@ runs:
       shell: bash
       run: |
         echo "nodejs_version=$(grep "^nodejs\s" .tool-versions | cut -f2 -d' ')" >> $GITHUB_OUTPUT
+    - name: Get pnpm version
+      id: pnpm_version
+      shell: bash
+      run: |
+        echo "pnpm_version=$(grep "^pnpm\s" .tool-versions | cut -f2 -d' ')" >> $GITHUB_OUTPUT
     - uses: ./.github/actions/node-install
       with:
         node-version: ${{ steps.nodejs_version.outputs.nodejs_version }}
+        pnpm-version: ${{ steps.pnpm_version.outputs.pnpm_version }}
         GITHUB_TOKEN: ${{ env.GITHUB_TOKEN }}
     - name: "Install dependencies"
       shell: bash
       run: |
-        npm ci
+        pnpm install --frozen-lockfile
     - name: Cache generated dependencies
       id: cache-generated
       uses: actions/cache@0057852bfaa89a56745cba8c7296529d2fc39830 # v4.3.0
@@ -59,7 +65,7 @@ runs:
       if: steps.cache-generated.outputs.cache-hit != 'true'
       shell: bash
       run: |
-        npm run generate-dependencies
+        pnpm run generate-dependencies
     - name: Run test - ${{ inputs.testType }}
       shell: bash
       run: |

.github/actions/node-install/action.yaml

@@ -1,25 +1,32 @@
 name: 'Node install and setup'
-description: 'Setup node and authenticate github package repository'
+description: 'Setup node with pnpm and authenticate github package repository'
 
 inputs:
   node-version:
     description: 'Node.js version'
     required: true
+  pnpm-version:
+    description: 'pnpm version'
+    required: true
   GITHUB_TOKEN:
     description: "Token for access to github package registry"
     required: true
 
 runs:
   using: 'composite'
   steps:
+    - name: 'Setup pnpm'
+      uses: pnpm/action-setup@fc06bc1257f339d1d5d8b3a19a8cae5388b55320 # v5.0.0
+      with:
+        version: '${{ inputs.pnpm-version }}'
+
     - name: 'Use Node.js'
       uses: actions/setup-node@53b83947a5a98c8d113130e565377fae1a50d02f # v6
       with:
         node-version: '${{ inputs.node-version }}'
-        cache: 'npm'
-        cache-dependency-path: '**/package-lock.json'
+        cache: 'pnpm'
 
-    - name: "Configure npm for GitHub Packages"
+    - name: "Configure pnpm for GitHub Packages"
       shell: bash
       env:
         GITHUB_TOKEN: ${{ inputs.GITHUB_TOKEN }}

.github/workflows/cicd-1-pull-request.yaml

@@ -32,6 +32,7 @@ jobs:
       build_timestamp: ${{ steps.variables.outputs.build_timestamp }}
       build_epoch: ${{ steps.variables.outputs.build_epoch }}
       nodejs_version: ${{ steps.variables.outputs.nodejs_version }}
+      pnpm_version: ${{ steps.variables.outputs.pnpm_version }}
       python_version: ${{ steps.variables.outputs.python_version }}
       terraform_version: ${{ steps.variables.outputs.terraform_version }}
       version: ${{ steps.variables.outputs.version }}
@@ -54,6 +55,7 @@ jobs:
           echo "build_timestamp=$(date --date=$datetime -u +'%Y%m%d%H%M%S')" >> $GITHUB_OUTPUT
           echo "build_epoch=$(date --date=$datetime -u +'%s')" >> $GITHUB_OUTPUT
           echo "nodejs_version=$(grep "^nodejs\s" .tool-versions | cut -f2 -d' ')" >> $GITHUB_OUTPUT
+          echo "pnpm_version=$(grep "^pnpm\s" .tool-versions | cut -f2 -d' ')" >> $GITHUB_OUTPUT
           echo "python_version=$(grep "^python\s" .tool-versions | cut -f2 -d' ')" >> $GITHUB_OUTPUT
           echo "terraform_version=$(grep "^terraform\s" .tool-versions | cut -f2 -d' ')" >> $GITHUB_OUTPUT
           echo "version=$(echo $version)" >> $GITHUB_OUTPUT
@@ -122,6 +124,7 @@ jobs:
       build_timestamp: "${{ needs.metadata.outputs.build_timestamp }}"
       build_epoch: "${{ needs.metadata.outputs.build_epoch }}"
       nodejs_version: "${{ needs.metadata.outputs.nodejs_version }}"
+      pnpm_version: "${{ needs.metadata.outputs.pnpm_version }}"
       python_version: "${{ needs.metadata.outputs.python_version }}"
       # TODO - Re-visit Trivy usage https://nhsd-jira.digital.nhs.uk/browse/CCM-15549
       # skip_trivy_package: ${{ needs.metadata.outputs.skip_trivy_package == 'true' }}
@@ -137,6 +140,7 @@ jobs:
       build_timestamp: "${{ needs.metadata.outputs.build_timestamp }}"
       build_epoch: "${{ needs.metadata.outputs.build_epoch }}"
       nodejs_version: "${{ needs.metadata.outputs.nodejs_version }}"
+      pnpm_version: "${{ needs.metadata.outputs.pnpm_version }}"
       python_version: "${{ needs.metadata.outputs.python_version }}"
       terraform_version: "${{ needs.metadata.outputs.terraform_version }}"
       version: "${{ needs.metadata.outputs.version }}"
@@ -150,6 +154,7 @@ jobs:
     with:
       build_datetime: "${{ needs.metadata.outputs.build_datetime }}"
       build_timestamp: "${{ needs.metadata.outputs.build_timestamp }}"
+      pnpm_version: "${{ needs.metadata.outputs.pnpm_version }}"
       build_epoch: "${{ needs.metadata.outputs.build_epoch }}"
       nodejs_version: "${{ needs.metadata.outputs.nodejs_version }}"
       python_version: "${{ needs.metadata.outputs.python_version }}"
@@ -164,12 +169,12 @@ jobs:
       contents: read
       id-token: write
     if: needs.metadata.outputs.does_pull_request_exist == 'true' || (github.event_name == 'pull_request' && (github.event.action == 'opened' || github.event.action == 'reopened'))
+    env:
+      APP_PEM_FILE: ${{ secrets.APP_PEM_FILE }}
+      APP_CLIENT_ID: ${{ secrets.APP_CLIENT_ID }}
     steps:
-      - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
       - name: Trigger dynamic environment creation
-        env:
-          APP_PEM_FILE: ${{ secrets.APP_PEM_FILE }}
-          APP_CLIENT_ID: ${{ secrets.APP_CLIENT_ID }}
         shell: bash
         run: |
           .github/scripts/dispatch_internal_repo_workflow.sh \

.github/workflows/cicd-3-deploy.yaml

@@ -46,6 +46,7 @@ jobs:
       build_timestamp: ${{ steps.variables.outputs.build_timestamp }}
       build_epoch: ${{ steps.variables.outputs.build_epoch }}
       nodejs_version: ${{ steps.variables.outputs.nodejs_version }}
+      pnpm_version: ${{ steps.variables.outputs.pnpm_version }}
       python_version: ${{ steps.variables.outputs.python_version }}
       terraform_version: ${{ steps.variables.outputs.terraform_version }}
       version: ${{ steps.variables.outputs.version }}
@@ -61,6 +62,7 @@ jobs:
           echo "build_timestamp=$(date --date=$datetime -u +'%Y%m%d%H%M%S')" >> $GITHUB_OUTPUT
           echo "build_epoch=$(date --date=$datetime -u +'%s')" >> $GITHUB_OUTPUT
           echo "nodejs_version=$(grep "^nodejs\s" .tool-versions | cut -f2 -d' ')" >> $GITHUB_OUTPUT
+          echo "pnpm_version=$(grep "^pnpm\s" .tool-versions | cut -f2 -d' ')" >> $GITHUB_OUTPUT
           echo "python_version=$(grep "^python\s" .tool-versions | cut -f2 -d' ')" >> $GITHUB_OUTPUT
           echo "terraform_version=$(grep "^terraform\s" .tool-versions | cut -f2 -d' ')" >> $GITHUB_OUTPUT
           echo "version=$(head -n 1 .version 2> /dev/null || echo unknown)" >> $GITHUB_OUTPUT

.github/workflows/stage-1-commit.yaml

@@ -19,6 +19,10 @@ on:
         description: "Node.js version, set by the CI/CD pipeline workflow"
         required: true
         type: string
+      pnpm_version:
+        description: "pnpm version, set by the CI/CD pipeline workflow"
+        required: true
+        type: string
       python_version:
         description: "Python version, set by the CI/CD pipeline workflow"
         required: true

.github/workflows/stage-2-test.yaml

@@ -19,6 +19,10 @@ on:
         description: "Node.js version, set by the CI/CD pipeline workflow"
         required: true
         type: string
+      pnpm_version:
+        description: "pnpm version, set by the CI/CD pipeline workflow"
+        required: true
+        type: string
       python_version:
         description: "Python version, set by the CI/CD pipeline workflow"
         required: true
@@ -77,18 +81,19 @@ jobs:
       - uses: ./.github/actions/node-install
         with:
           node-version: ${{ inputs.nodejs_version }}
+          pnpm-version: ${{ inputs.pnpm_version }}
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
       - name: "Repo setup"
         run: |
-          npm ci
+          pnpm install --frozen-lockfile
       - name: "Generate dependencies"
         run: |
-          npm run generate-dependencies
+          pnpm run generate-dependencies
           git diff --exit-code
   test-unit:
     name: "Unit tests"
     runs-on: ubuntu-latest
-    timeout-minutes: 7
+    timeout-minutes: 15
     permissions:
       contents: read
       packages: read
@@ -100,7 +105,7 @@ jobs:
           node-version: ${{ inputs.nodejs_version }}
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
       - name: "Install dependencies"
-        run: npm ci
+        run: pnpm install --frozen-lockfile
       - name: "Setup Python"
         uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6
         with:
@@ -122,7 +127,7 @@ jobs:
       - name: "Generate dependencies"
         if: steps.schema-cache.outputs.cache-hit != 'true'
         run: |
-          npm run generate-dependencies
+          pnpm run generate-dependencies
       - name: "Run unit test suite"
         run: |
           make test-unit
@@ -159,9 +164,10 @@ jobs:
       - uses: ./.github/actions/node-install
         with:
           node-version: ${{ inputs.nodejs_version }}
+          pnpm-version: ${{ inputs.pnpm_version }}
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
       - name: "Install dependencies"
-        run: npm ci --ignore-scripts
+        run: pnpm install --frozen-lockfile --ignore-scripts
       - name: "Cache generated dependencies"
         id: schema-cache
         uses: actions/cache@0057852bfaa89a56745cba8c7296529d2fc39830 # v4.3.0
@@ -177,7 +183,7 @@ jobs:
       - name: "Generate dependencies"
         if: steps.schema-cache.outputs.cache-hit != 'true'
         run: |
-          npm run generate-dependencies
+          pnpm run generate-dependencies
       - name: "Run contract test suite"
         run: |
           make test-contract
@@ -206,8 +212,16 @@ jobs:
           cache-dependency-path: '**/requirements*.txt'
       - uses: ./.github/actions/node-install
         with:
+          pnpm-version: ${{ inputs.pnpm_version }}
           node-version: ${{ inputs.nodejs_version }}
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+      - name: "Install Python dev dependencies"
+        run: |
+          for req in src/digital-letters-events/requirements-dev.txt utils/py-mock-mesh/requirements-dev.txt src/python-schema-generator/requirements-dev.txt; do
+            if [ -f "$req" ]; then
+              pip install -r "$req"
+            fi
+          done
       - name: "Run linting"
         run: |
           make test-lint
@@ -225,6 +239,7 @@ jobs:
         uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5
       - uses: ./.github/actions/node-install
         with:
+          pnpm-version: ${{ inputs.pnpm_version }}
           node-version: ${{ inputs.nodejs_version }}
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
       - name: "Run typecheck"

.github/workflows/stage-3-build.yaml

@@ -19,6 +19,10 @@ on:
         description: "Node.js version, set by the CI/CD pipeline workflow"
         required: true
         type: string
+      pnpm_version:
+        description: "pnpm version, set by the CI/CD pipeline workflow"
+        required: true
+        type: string
       python_version:
         description: "Python version, set by the CI/CD pipeline workflow"
         required: true
@@ -75,6 +79,8 @@ jobs:
       - name: "Checkout code"
         uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5
       - name: "Build docs"
-        uses: NHSDigital/nhs-notify-shared-modules/.github/actions/build-docs@3.1.6
+        uses: NHSDigital/nhs-notify-shared-modules/.github/actions/build-docs@91645a94db7d0177b159716f191f878b9659d980 # CCM-16572_pnpmMigration
         with:
           version: "${{ inputs.version }}"
+          node_version: "${{ inputs.nodejs_version }}"
+          pnpm_filters: "--filter ./src/cloudevents --filter ./src/eventcatalog"

.tool-versions

@@ -2,6 +2,7 @@ act 0.2.64
 gitleaks 8.24.0
 jq 1.6
 nodejs 24.10.0
+pnpm 10.33.0
 pre-commit 3.6.0
 python 3.14.0
 ruby 3.2.0

AGENTS.md

@@ -12,7 +12,7 @@ Keep anything language or tool-specific in nested `AGENTS.md` files (for example
 At a glance, the main areas are:
 
 - `infrastructure/terraform/` – Terraform components, and shared modules for AWS accounts and environments.
-- `lambdas/` – TypeScript lambda projects (each with their own `package.json`, Jest config, etc.). Root level packages.json defines workspaces and scripts. Tests for the lambda are stored in `lambdas/{name}/src/__test`.
+- `lambdas/` – TypeScript lambda projects (each with their own `package.json`, Jest config, etc.). Root level package.json defines scripts. Tests for the lambda are stored in `lambdas/{name}/src/__test`.
 - `src/` and `utils/` – Shared code and utilities (for example `utils/logger`).
 - `docs/` – Documentation site, ADRs, RFCS, and other long‑form docs.
 - `.github/workflows/` and `.github/actions/` – GitHub Actions workflows and composite actions.
@@ -21,27 +21,40 @@ At a glance, the main areas are:
 
 Agents should look for a nested `AGENTS.md` in or near these areas before making non‑trivial changes.
 
+## Root pnpm-workspace.yaml - role and usage
+
+The root `pnpm-workspace.yaml` is the manifest for configuring the pnpm tool, and workspace packages.
+
+- Packages: Declares the set of workspace packages (e.g. under `lambdas/`, `utils/`, `tests/`, `scripts/`, `src/`, `docs/`). Agents should add a new package path here when introducing a new workspace package.
+- Catalogs: Defines named version catalogs (`lint`, `test`, `tools`, `build`) that centralise dependency version ranges. Workspace packages reference these with the `catalog:<name>` protocol (e.g. `"jest": "catalog:test"`) instead of hardcoding version ranges in each `package.json`.
+
+Agent guidance for catalogs:
+
+- When adding a dependency that belongs to an existing catalog category, add the version range to the appropriate catalog in `pnpm-workspace.yaml` and reference it as `"catalog:<name>"` in the consuming `package.json`.
+- Do not hardcode version ranges in workspace `package.json` files for dependencies that already exist in a catalog — always use the `catalog:` protocol.
+- When updating a dependency version, change it in the catalog entry only; all workspace packages referencing that catalog entry will pick up the new version automatically.
+- If a dependency does not fit any existing catalog, create a new catalog with a suitable name and add the version range there. All dependencies must be managed through catalogs — never hardcode version ranges directly in a `package.json`.
+
 ## Root package.json – role and usage
 
-The root `package.json` is the orchestration manifestgit co for this repo. It does not ship application code; it wires up shared dev tooling and delegates to workspace-level projects.
+The root `package.json` is the orchestration manifest for this repo. It does not ship application code; it wires up shared dev tooling and delegates to workspace-level projects.
 
-- Workspaces: Declares the set of npm workspaces (e.g. under `lambdas/`, `utils/`, `tests/`, `scripts/`). Agents should add a new workspace path here when introducing a new npm project.
-- Scripts: Provides top-level commands that fan out across workspaces using `--workspaces` (lint, typecheck, unit tests) and project-specific runners (e.g. `lambda-build`).
-- Dev tool dependencies: Centralises Jest, TypeScript, ESLint configurations and plugins to keep versions consistent across workspaces. Workspace projects should rely on these unless a local override is strictly needed.
-- Overrides/resolutions: Pins transitive dependencies (e.g. Jest/react-is) to avoid ecosystem conflicts. Agents must not remove overrides without verifying tests across all workspaces.
+- Scripts: Provides top-level commands that fan out across workspaces using `pnpm -r` (lint, typecheck, unit tests) and project-specific runners.
+- Dev tool dependencies: Centralises Jest, TypeScript, ESLint configurations and plugins via pnpm catalogs to keep versions consistent across workspaces. Workspace projects should rely on catalog references unless a local override is strictly needed.
+- Overrides: Pins transitive dependencies to avoid ecosystem conflicts. Agents must not remove overrides without verifying tests across all workspaces.
 
 Agent guidance:
 
-- Before adding or removing a workspace, update the root `workspaces` array and ensure CI scripts still succeed with `npm run lint`, `npm run typecheck`, and `npm run test:unit` at the repo root.
-- When adding repo-wide scripts, keep names consistent with existing patterns (e.g. `lint`, `lint:fix`, `typecheck`, `test:unit`, `lambda-build`) and prefer `--workspaces` fan-out.
+- Before adding or removing a workspace, update the `packages` array in `pnpm-workspace.yaml` and ensure CI scripts still succeed with `pnpm run lint`, `pnpm run typecheck`, and `pnpm run test:unit` at the repo root.
+- When adding repo-wide scripts, keep names consistent with existing patterns (e.g. `lint`, `lint:fix`, `typecheck`, `test:unit`) and prefer `pnpm -r` or turbo fan-out.
 - Do not publish from the root. If adding a new workspace intended for publication, mark that workspace package as `private: false` and keep the root as private.
 - Validate changes by running the repo pre-commit hooks: `make githooks-run`.
 
 Success criteria for changes affecting the root `package.json`:
 
-- `npm run lint`, `npm run typecheck`, and `npm run test:unit` pass at the repo root.
-- Workspace discovery is correct (new projects appear under `npm run typecheck --workspaces`).
-- No regression in lambda build tooling (`npm run lambda-build`).
+- `pnpm run lint`, `pnpm run typecheck`, and `pnpm run test:unit` pass at the repo root.
+- Workspace discovery is correct (new projects appear when running tests).
+- No regression in build tooling.
 
 ## What Agents Can / Can’t Do
 
@@ -81,7 +94,7 @@ When proposing a change, agents should:
 
   to catch formatting and basic lint issues. Domain specific checks will be defined in appropriate nested AGENTS.md files.
 
-- Suggest at least one extra validation step (for example `npm test` in a lambda, or triggering a specific workflow).
+- Suggest at least one extra validation step (for example `pnpm test` in a lambda, or triggering a specific workflow).
 - Any required follow up activites which fall outside of the current task's scope should be clearly marked with a 'TODO: CCM-12345' comment. The human user should be prompted to create and provide a JIRA ticket ID to be added to the comment.
 
 ## Security & Safety

Makefile

@@ -19,7 +19,7 @@ dependencies:: # Install dependencies needed to build and test the project @Pipe
 	$(MAKE) -C lambdas/mesh-download install
 	$(MAKE) -C lambdas/report-sender install
 	./scripts/set-github-token.sh
-	npm install --workspaces
+	pnpm install
 	$(MAKE) generate
 
 dependencies-docs:: # Install documentation dependencies @Pipeline
@@ -29,7 +29,7 @@ build: dependencies-docs # Build the project artefact @Pipeline
 	$(MAKE) -C docs build
 
 generate: # Generate any autogenerated output @Pipeline
-	npm run generate-dependencies
+	pnpm run generate-dependencies
 
 debug:
 	$(MAKE) -C docs debug
@@ -53,7 +53,7 @@ clean:: # Clean-up project resources (main) @Operations
 	$(MAKE) -C utils/py-mock-mesh clean && \
 	$(MAKE) -C src/python-schema-generator clean && \
 	rm -f .version
-	npm run clean
+	pnpm run clean
 
 config:: _install-dependencies version dependencies # Configure development environment (main) @Configuration
 

docs/webpack.config.js

@@ -40,7 +40,7 @@ module.exports = {
         }),
       new CopyPlugin({
         patterns: [
-          { from: "../node_modules/reveal.js-menu/", to: "reveal.js-menu/" },
+          { from: "node_modules/reveal.js-menu/", to: "reveal.js-menu/" },
           //{ from: "../node_modules/reveal.js-menu/font-awesome/", to: "reveal.js-menu/font-awesome/" },
           //{ from: "../node_modules/reveal.js-menu/menu.css", to: "reveal.js-menu/menu.css" },
         ],