From a6cd876c3809cbd40c97b8a4b272872bff3b3a88 Mon Sep 17 00:00:00 2001 From: andykay-nhs Date: Tue, 28 Apr 2026 09:24:49 +0100 Subject: [PATCH 1/5] Begin updating readme --- README.md | 175 +++++++++++++++++++++++++++++++----------------------- 1 file changed, 102 insertions(+), 73 deletions(-) diff --git a/README.md b/README.md index 14d812a9de..9bafd23f74 100644 --- a/README.md +++ b/README.md @@ -1,116 +1,145 @@ -# NHS Notify Template Management (WebUI) Repository +# NHS Notify – Template Management Web UI -## Setting up locally +This repository contains the **Template Management Web UI** for NHS Notify. -### Git +It provides an interface for: -- Make sure you have GitHub access with the right permissions -- Setup git locally on your machine -- Set your local git email as you `*@nhs.net` email `e.g. git config --global user.email "firstname.lastname1@nhs.net"` -- Setup commit signing (this is required before you can commit any code to the repository). This is a very good resource to help Mac users `https://gist.github.com/troyfontaine/18c9146295168ee9ca2b30c00bd1b41e` -- Pull the repository here `git@github.com:NHSDigital/nhs-notify-web-template-management.git` +- Creating and managing message templates (NHS App messages, email, SMS and letters) +- Configuring routing rules for message delivery +- Previewing and submitting templates into the wider Notify platform -### Development and Tools +> ⚠️ This application is tightly coupled to AWS infrastructure. Local development requires provisioning sandbox infrastructure. -- Install `asdf` [HERE](https://asdf-vm.com/guide/getting-started.html#_2-download-asdf). We use this tool to manage the required version for packages (this can be found in the `.tool-versions` file at the root of the project) on the project. You can use other tools usch as `brew`, `apt`, etc, but you will be risking having different package versions to other developers. -- Then you need to install the following plugins: +--- -```shell - asdf plugin add nodejs - asdf plugin add direnv - asdf plugin add terraform - asdf plugin add gitleaks - asdf plugin add pre-commit -``` +## Overview + +This project is **not just a frontend app** — it’s part of a wider system that depends on: + +- AWS infrastructure (via Terraform) +- Backend services (lambdas) +- Shared platform components + +Because of this, **local development mimics production** by provisioning real cloud resources. + +## Prerequisites + +Before getting started, you should have: + +### Access & Accounts -- Now you can install the tools, and they will be runnable from within the `nhs-notify-web-template-management` directory: +- GitHub access to this repository +- AWS account access (with permissions to provision infrastructure OR someone has provisioned resources on your behalf) +- NHS email configured for git (`*@nhs.net`) + +### Installed Tools + +We standardise tooling using `asdf`: + +- [asdf](https://asdf-vm.com/) +- Node.js (via asdf) +- Terraform (via asdf) +- AWS CLI +- Git + +--- + +## ⚙️ Setup + +### 1. Clone the repository ```shell - asdf install +git clone git@github.com:NHSDigital/nhs-notify-web-template-management.git +cd nhs-notify-web-template-management ``` -- Now you can run the command below to install the packages in the project: +--- + +### 2. Configure Git ```shell - npm install +git config --global user.email "firstname.lastname@nhs.net" ``` -### Environment Variables and .env.template +You must also enable commit signing (required for commits). + +Helpful guide: + -This repository provides a `.env.template` file at the root. This file contains example environment variables required for local development and deployment. +--- -**How to use:** +### 3. Install tooling (asdf) -1. Copy `.env.template` to a new file named `.env` in the same directory: +```shell +asdf plugin add nodejs +asdf plugin add direnv +asdf plugin add terraform +asdf plugin add gitleaks +asdf plugin add pre-commit + +asdf install +``` - ```shell - cp .env.template .env - ``` +--- -2. Open `.env` and update the values as needed for your environment. For example, set your GitHub personal access token and username: +### 4. Install dependencies - - `GITHUB_TOKEN` – Your GitHub Personal Access Token with packages:read permissions. - - `GITHUB_ACTOR` – Your GitHub username associated with the token +```shell +npm install +``` -3. Save the file. The application and scripts will now use these environment variables. +--- -**Tip:** +## 🔐 AWS Setup -- Keep `.env` files out of version control. The `.env.template` is provided as a reference for required variables. +To run the project e2e you will need to provision resources in an AWS sandbox environment. Alternatively, someone else in the team can do this for you and this step can be skipped. -### Running the project locally +Similarly, to run playwright tests locally you will need permissions to access the infrastructure you're pointing to so that test data can be automatically seeded as part of running tests. If this is not configured properly then tests will fail to run. -1. To create a Terraform backend sandbox, run: +### Install AWS CLI - ```shell - npm run create-backend-sandbox - ``` +```shell +asdf plugin add awscli +asdf install awscli +``` -2. Then in a separate terminal, run the app locally: +### Configure credentials - ```shell - npm run dev - ``` +```shell +aws configure +``` -3. Open your browser and go to `localhost:3000` to view the app. +Or via SSO: -4. To destroy a Terraform backend sandbox, run: +```shell +aws configure sso +``` - ```shell - npm run destroy-backend-sandbox - ``` +Make sure a default profile is setup. -5. (Optional) Create a `.env` file at `frontend/.env` and add `INCLUDE_AUTH_PAGES=true` to include the local auth pages when doing a production Next build +```shell +export AWS_DEFAULT_PROFILE={PROFILE_NAME_YOU_SETUP} +``` -### Other commands +--- -- Unit test `npm run test:unit` -- Accessibility test `npm run test:accessibility` +## 🔧 Environment Configuration -You can find more commands in the `package.json` file +### 1. Create .env -### Running Team and IAM Web Auth projects locally +```shell +cp .env.template .env +``` -Read more in the [README.md](./local/README.md). +Update required values: -### Project structure +- **GITHUB_TOKEN**: This is a github Personal Access Token with packages:read permissions and configured access to the NHS Digital github organisation. (Only needed if provisioning sandbox infrastructure) -- components `./src/components` -- pages `./src/app` -- SCSS Styles `./src/styles` -- App contents `./src/content -- Unit tests (Components) `./src/__tests__/components` -- Unit tests (Pages) `./src/__tests__/pages` -- Utilities functions `./src/utils` -- Types `./src/types` +--- -### Shared Terraform Modules +### 2. Generate environment-specific files -Before you setup modules for this repository and find that there might be modules that can be reused elsewhere, please do check out `https://github.com/NHSDigital/nhs-notify-shared-modules/`. If you find that the modules are shareable, you should set them up there as a separate PR and get that merged in and potentially tag the commit after testing it, so that it can be a stable release that can be used across all repos on Notify should others find the need to re-use that new module. You can simply point to the reference in your module call as below: +npm run create-env-file +npm run create-amplify-outputs -```hcl -module "amp_branch" { - source = "git::https://github.com/NHSDigital/nhs-notify-shared-modules.git//infrastructure/modules/amp_branch?ref=v1.0.0" - ... -} -``` +These steps are required for the frontend to correctly connect to provisioned infrastructure. From c84c000750b82d3630f052eaf013d67d5c624fb6 Mon Sep 17 00:00:00 2001 From: andykay-nhs Date: Wed, 6 May 2026 11:41:37 +0100 Subject: [PATCH 2/5] Finish running locally section --- README.md | 133 ++++++++++++++++++++++++++++++++++++++++++++------- package.json | 1 + 2 files changed, 116 insertions(+), 18 deletions(-) diff --git a/README.md b/README.md index 9bafd23f74..d3930d6bee 100644 --- a/README.md +++ b/README.md @@ -8,19 +8,16 @@ It provides an interface for: - Configuring routing rules for message delivery - Previewing and submitting templates into the wider Notify platform -> ⚠️ This application is tightly coupled to AWS infrastructure. Local development requires provisioning sandbox infrastructure. - ---- - ## Overview -This project is **not just a frontend app** — it’s part of a wider system that depends on: +This project is **not just a frontend app** it’s part of a wider system that depends on: - AWS infrastructure (via Terraform) - Backend services (lambdas) - Shared platform components -Because of this, **local development mimics production** by provisioning real cloud resources. +Because of this, local development requires provisioning real cloud resources inside of sandbox environments. Each dev can provision their own sandbox environment +and point a locally running instance of the Next.js app the provisioned environment. ## Prerequisites @@ -31,6 +28,7 @@ Before getting started, you should have: - GitHub access to this repository - AWS account access (with permissions to provision infrastructure OR someone has provisioned resources on your behalf) - NHS email configured for git (`*@nhs.net`) +- Be a member of the [NHS Digital](https://github.com/NHSDigital) github organisation ### Installed Tools @@ -42,9 +40,7 @@ We standardise tooling using `asdf`: - AWS CLI - Git ---- - -## ⚙️ Setup +## Setup ### 1. Clone the repository @@ -88,13 +84,12 @@ asdf install npm install ``` ---- - ## 🔐 AWS Setup To run the project e2e you will need to provision resources in an AWS sandbox environment. Alternatively, someone else in the team can do this for you and this step can be skipped. -Similarly, to run playwright tests locally you will need permissions to access the infrastructure you're pointing to so that test data can be automatically seeded as part of running tests. If this is not configured properly then tests will fail to run. +Similarly, to run playwright tests locally you will need permissions to access the infrastructure you're pointing to so that test data can be automatically seeded. If this is not configured properly then tests will fail during their +setup phase. ### Install AWS CLI @@ -121,11 +116,9 @@ Make sure a default profile is setup. export AWS_DEFAULT_PROFILE={PROFILE_NAME_YOU_SETUP} ``` ---- +## Running Locally -## 🔧 Environment Configuration - -### 1. Create .env +### 1. Create root .env ```shell cp .env.template .env @@ -137,9 +130,113 @@ Update required values: --- -### 2. Generate environment-specific files +### 2. Generate frontend .env file +```shell npm run create-env-file +``` + +--- + +### 3 Setup a sandbox environment + +#### 3.1 Use someone else's + +If someone else has provisioned a sandbox environment for you and setup the clients and user login then you just need the output file `sandbox_tf_outputs.json`. Copy this to the root of the repo and run the command + +#### 3.2 Or provision your own + +```shell +npm run create-backend-sandbox -- {YOUR_SHORTCODE_HERE} +``` + +This step will provision infrastructure and deploy any backend services required by the frontend. + +Each sandbox environment should have a unique identifier to differentiate their provisioned resources under the same AWS account. Any short string of text can be passed in as an arg but devs typically use their HSCIC account shortcode so resources belonging to their environment can be easily identified. + +#### 3.3 Seed clients and a user + +Running this will seed clients into SSM and create a user within Cognito with the email and password provided so that you can log into the frontend once it's running. + +```shell +npm run sandbox-auth -- {EMAIL} {PASSWORD} +``` + +```shell npm run create-amplify-outputs +``` + +--- + +### 4. Start the app + +Start the Next.js dev server. + +```shell +npm run dev +``` + +Alternatively, use the following command to use an optimised production build of the frontend. + +```shell +npm run build --workspace frontend && npm run start --workspace frontend +``` + +--- + +### 5. Destroy sandbox (Optional) + +```shell +npm run destroy-backend-sandbox -- {YOUR_SHORTCODE_HERE} +``` + +## Running Tests + +### Unit Tests + +```shell +npm run test:unit +``` + +use the `--u` arg to update snapshots after an intentional implementation change + +```shell +npm run test:unit -- --u +``` + +### Playwright + +All playwright tests are in the directory `/tests/test-team` + +Assuming the following prerequisites are met + +- Provisioned sanbodx environment +- Valid `sandbox_tf_outputs.json` file at the repo root +- Local AWS credentials configured with default profile + +Test suites can be run with the following commands. This will run each test suite using the CLI. + +```shell +npm run test:accessibility +npm run test:api +npm run test:backend +npm run test:component +npm run test:e2e +npm run test:routing-component +``` + +Alternatively, use the Playwright UI to run tests using the command + +```shell +npx playwright test --ui -c {CONFIG} +``` + +Configs for each test suite can be found under `/tests/test-team/config`. + +Example: Run Playwright UI for e2e tests + +```shell +npx playwright test --ui -c config/e2e/e2e.config.ts +``` -These steps are required for the frontend to correctly connect to provisioned infrastructure. +These commands will automatically build and run an optimised production version of the frontend if there isn't one already running. diff --git a/package.json b/package.json index bf54db2c02..bcf7fbd308 100644 --- a/package.json +++ b/package.json @@ -47,6 +47,7 @@ "build": "npm run create-env-file && npm run build --workspace frontend", "create-amplify-outputs": "tsx ./scripts/create-amplify-outputs.ts", "create-backend-sandbox": "./scripts/create_backend_sandbox.sh", + "sandbox-auth": "./scripts/sandbox_auth.sh", "create-env-file": "tsx ./scripts/create-env-file.ts", "destroy-backend-sandbox": "./scripts/destroy_backend_sandbox.sh", "dev": "npm run dev --workspace frontend --if-present", From ffe2cdc067c9044fc1850c337bcf4274e4d995db Mon Sep 17 00:00:00 2001 From: andykay-nhs Date: Wed, 6 May 2026 16:23:34 +0100 Subject: [PATCH 3/5] Add project structure --- README.md | 25 ++++++++++++++++++++++--- 1 file changed, 22 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index d3930d6bee..2eeb75fadc 100644 --- a/README.md +++ b/README.md @@ -10,14 +10,33 @@ It provides an interface for: ## Overview -This project is **not just a frontend app** it’s part of a wider system that depends on: +This project is **not just a frontend app** it’s a full stack application that depends on: - AWS infrastructure (via Terraform) - Backend services (lambdas) - Shared platform components -Because of this, local development requires provisioning real cloud resources inside of sandbox environments. Each dev can provision their own sandbox environment -and point a locally running instance of the Next.js app the provisioned environment. +Local development requires provisioning real cloud resources inside of sandbox environments. Each dev can provision their own sandbox environment and point a locally running instance of the Next.js app the provisioned environment. + +## Project Structure + +```shell +├── frontend - Contains the main web UI application (Next.js) +├── infrastructure - Serverless backend functions +├── lambdas - Terraform infrastructure definitions +├── packages - Shared code across workspaces +├── scripts - Utility scripts used by the repo +├── tests - Higher-level E2E, component and contract tests +└── utils - General-purpose helpers not tied to a specific workspace +``` + +- frontend - Contains the main web UI application (Next.js) +- lambdas - Serverless backend functions +- infrastructure - Terraform infrastructure definitions +- packages - Shared code across workspaces +- scripts - Utility scripts used by the repo +- tests - Higher-level E2E, component and contract tests +- utils - General-purpose helpers not tied to a specific workspace ## Prerequisites From 5f5d9be707c193be12342fd81d87338461370414 Mon Sep 17 00:00:00 2001 From: andykay-nhs Date: Thu, 7 May 2026 11:16:25 +0100 Subject: [PATCH 4/5] Address spelling errors --- README.md | 36 +++++++++++++----------------------- 1 file changed, 13 insertions(+), 23 deletions(-) diff --git a/README.md b/README.md index 2eeb75fadc..f837cacca0 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -# NHS Notify – Template Management Web UI +# NHS Notify Template Management (WebUI) Repository This repository contains the **Template Management Web UI** for NHS Notify. @@ -8,33 +8,21 @@ It provides an interface for: - Configuring routing rules for message delivery - Previewing and submitting templates into the wider Notify platform -## Overview - This project is **not just a frontend app** it’s a full stack application that depends on: - AWS infrastructure (via Terraform) - Backend services (lambdas) - Shared platform components -Local development requires provisioning real cloud resources inside of sandbox environments. Each dev can provision their own sandbox environment and point a locally running instance of the Next.js app the provisioned environment. +Local development requires provisioning real cloud resources inside of sandbox environments. Each developer can provision their own sandbox environment and point a locally running instance of the Next.js app the provisioned environment. ## Project Structure -```shell -├── frontend - Contains the main web UI application (Next.js) -├── infrastructure - Serverless backend functions -├── lambdas - Terraform infrastructure definitions -├── packages - Shared code across workspaces -├── scripts - Utility scripts used by the repo -├── tests - Higher-level E2E, component and contract tests -└── utils - General-purpose helpers not tied to a specific workspace -``` - - frontend - Contains the main web UI application (Next.js) - lambdas - Serverless backend functions - infrastructure - Terraform infrastructure definitions - packages - Shared code across workspaces -- scripts - Utility scripts used by the repo +- scripts - Utility scripts used by the repository - tests - Higher-level E2E, component and contract tests - utils - General-purpose helpers not tied to a specific workspace @@ -44,10 +32,10 @@ Before getting started, you should have: ### Access & Accounts -- GitHub access to this repository +- Github access to this repository - AWS account access (with permissions to provision infrastructure OR someone has provisioned resources on your behalf) - NHS email configured for git (`*@nhs.net`) -- Be a member of the [NHS Digital](https://github.com/NHSDigital) github organisation +- Be a member of the [NHS Digital](https://github.com/NHSDigital) Github organisation ### Installed Tools @@ -103,7 +91,7 @@ asdf install npm install ``` -## 🔐 AWS Setup +## AWS Setup To run the project e2e you will need to provision resources in an AWS sandbox environment. Alternatively, someone else in the team can do this for you and this step can be skipped. @@ -119,6 +107,8 @@ asdf install awscli ### Configure credentials +Configure access to the AWS template management dev account + ```shell aws configure ``` @@ -145,7 +135,7 @@ cp .env.template .env Update required values: -- **GITHUB_TOKEN**: This is a github Personal Access Token with packages:read permissions and configured access to the NHS Digital github organisation. (Only needed if provisioning sandbox infrastructure) +- **GITHUB_TOKEN**: This is a Github Personal Access Token with packages:read permissions and configured access to the NHS Digital Github organisation. (Only needed if provisioning sandbox infrastructure) --- @@ -189,7 +179,7 @@ npm run create-amplify-outputs ### 4. Start the app -Start the Next.js dev server. +Start the Next.js development server. ```shell npm run dev @@ -217,7 +207,7 @@ npm run destroy-backend-sandbox -- {YOUR_SHORTCODE_HERE} npm run test:unit ``` -use the `--u` arg to update snapshots after an intentional implementation change +use the `--u` argument to update snapshots after an intentional implementation change ```shell npm run test:unit -- --u @@ -229,8 +219,8 @@ All playwright tests are in the directory `/tests/test-team` Assuming the following prerequisites are met -- Provisioned sanbodx environment -- Valid `sandbox_tf_outputs.json` file at the repo root +- Provisioned sandbox environment +- Valid `sandbox_tf_outputs.json` file at the repository root - Local AWS credentials configured with default profile Test suites can be run with the following commands. This will run each test suite using the CLI. From 27f86c03da6f21aedb2747eb1b5519d2b97aa8dd Mon Sep 17 00:00:00 2001 From: andykay-nhs Date: Thu, 21 May 2026 14:30:50 +0100 Subject: [PATCH 5/5] Add githooks section + accept some words --- README.md | 24 ++++++++++++------- .../config/vocabularies/words/accept.txt | 9 +++++++ 2 files changed, 25 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index f837cacca0..684ee5e6ef 100644 --- a/README.md +++ b/README.md @@ -69,6 +69,14 @@ You must also enable commit signing (required for commits). Helpful guide: +#### 2.1 Githooks + +Run the following command to setup a pre-commit git hook that performs several linting and validation checks before any changes are committed. The same steps will be run in the CI pipeline when you open a pull request. + +```shell +make githooks-config +``` + --- ### 3. Install tooling (asdf) @@ -149,10 +157,14 @@ npm run create-env-file ### 3 Setup a sandbox environment -#### 3.1 Use someone else's +#### 3.1 Use an existing output If someone else has provisioned a sandbox environment for you and setup the clients and user login then you just need the output file `sandbox_tf_outputs.json`. Copy this to the root of the repo and run the command +```shell +npm run create-amplify-outputs +``` + #### 3.2 Or provision your own ```shell @@ -161,7 +173,7 @@ npm run create-backend-sandbox -- {YOUR_SHORTCODE_HERE} This step will provision infrastructure and deploy any backend services required by the frontend. -Each sandbox environment should have a unique identifier to differentiate their provisioned resources under the same AWS account. Any short string of text can be passed in as an arg but devs typically use their HSCIC account shortcode so resources belonging to their environment can be easily identified. +Each sandbox environment should have a unique identifier to differentiate their provisioned resources under the same AWS account. Any short string of text can be passed in as an argument but devs typically use their HSCIC account shortcode so resources belonging to their environment can be easily identified. #### 3.3 Seed clients and a user @@ -171,10 +183,6 @@ Running this will seed clients into SSM and create a user within Cognito with th npm run sandbox-auth -- {EMAIL} {PASSWORD} ``` -```shell -npm run create-amplify-outputs -``` - --- ### 4. Start the app @@ -185,7 +193,7 @@ Start the Next.js development server. npm run dev ``` -Alternatively, use the following command to use an optimised production build of the frontend. +Alternatively, use the following command to use an optimised production build of the frontend. (useful for running playwright tests) ```shell npm run build --workspace frontend && npm run start --workspace frontend @@ -207,7 +215,7 @@ npm run destroy-backend-sandbox -- {YOUR_SHORTCODE_HERE} npm run test:unit ``` -use the `--u` argument to update snapshots after an intentional implementation change +Use the `--u` argument to update snapshots after an intentional implementation change. ```shell npm run test:unit -- --u diff --git a/scripts/config/vale/styles/config/vocabularies/words/accept.txt b/scripts/config/vale/styles/config/vocabularies/words/accept.txt index a19984914b..859936f3dc 100644 --- a/scripts/config/vale/styles/config/vocabularies/words/accept.txt +++ b/scripts/config/vale/styles/config/vocabularies/words/accept.txt @@ -1,14 +1,19 @@ +asdf Bitwarden bot Cognito +Configs Cyber Dependabot +dev +devs draw.io drawio endcapture endfor endraw Git[Hh]ub +Githooks GitHub Gitleaks Grype @@ -21,10 +26,14 @@ onboarding Podman Python rawContent +repo sed +Serverless +shortcode Syft Terraform toolchain Trufflehog +utils [Vv]alidators Zod