nrf-backend

Core delivery platform Node.js Backend Template.

• nrf-backend
  • Requirements
    • Node.js
  • Local development
    • Setup
    • Development
    • Testing
    • Production
    • Npm scripts
    • Update dependencies
    • Formatting
      • Windows prettier issue
    • API documentation
    • Keeping Swagger docs in sync
  • Development helpers
    • Proxy
  • Docker
    • Development image
    • Production image
    • Docker Compose
    • Dependabot
    • SonarCloud
  • Licence
    • About the licence

Requirements

Node.js

Please install Node.js >= v22 and npm >= v11. You will find it easier to use the Node Version Manager nvm

To use the correct version of Node.js for this application, via nvm:

cd nrf-backend
nvm use

Local development

Setup

Install application dependencies:

npm ci

Development

To run the application in development mode run:

npm run dev

Testing

To test the application run:

npm run test

Production

To mimic the application running in production mode locally run:

npm start

Npm scripts

All available Npm scripts can be seen in package.json. To view them in your command line run:

npm run

Update dependencies

To update dependencies use npm-check-updates:

The following script is a good start. Check out all the options on the npm-check-updates

ncu --interactive --format group

Formatting

Windows prettier issue

If you are having issues with formatting of line breaks on Windows update your global git config by running:

git config --global core.autocrlf false

API documentation

Swagger UI is available at /docs when the server is running. The OpenAPI spec is generated from @openapi JSDoc annotations in the route and controller files.

Keeping Swagger docs in sync

An AI (Claude Code) skill is provided to audit and fix the @openapi annotations so they match the actual endpoint implementations.

Run it from nrf-solution with:

/sync-swagger

Development helpers

Proxy

We are using forward-proxy which is set up by default. To make use of this: import { fetch } from 'undici' then because of the setGlobalDispatcher(new ProxyAgent(proxyUrl)) calls will use the ProxyAgent Dispatcher

If you are not using Wreck, Axios or Undici or a similar http that uses Request. Then you may have to provide the proxy dispatcher:

To add the dispatcher to your own client:

import { ProxyAgent } from 'undici'

return await fetch(url, {
  dispatcher: new ProxyAgent({
    uri: proxyUrl,
    keepAliveTimeout: 10,
    keepAliveMaxTimeout: 10
  })
})

Docker

Development image

Build:

docker build --target development --no-cache --tag nrf-backend:development .

Run:

docker run -e PORT=3001 -p 3001:3001 nrf-backend:development

Production image

Build:

docker build --no-cache --tag nrf-backend .

Run:

docker run -e PORT=3001 -p 3001:3001 nrf-backend

Docker Compose

A local environment with:

• Localstack for AWS services (S3, SQS)
• Redis
• CDP Uploader
• Caddy (reverse proxy)
• This service.
• A commented out frontend example.

Caddy sits in front of the compose services for local development, providing a single entry point on port 4000 that proxies requests to the appropriate service. For example this ensures requests to the /scan-and-upload/ URL are routed correctly to the cdp-uploader local service.

docker compose up --build -d

Dependabot

We have added an example dependabot configuration file to the repository. You can enable it by renaming the .github/example.dependabot.yml to .github/dependabot.yml

SonarCloud

Instructions for setting up SonarCloud can be found in sonar-project.properties

Database diagram

Quote database diagram

Generated using the create-database-diagram skill in nrf-solution repository.

Licence

THIS INFORMATION IS LICENSED UNDER THE CONDITIONS OF THE OPEN GOVERNMENT LICENCE found at:

http://www.nationalarchives.gov.uk/doc/open-government-licence/version/3

The following attribution statement MUST be cited in your products and applications when using this information.

Contains public sector information licensed under the Open Government license v3

About the licence

The Open Government Licence (OGL) was developed by the Controller of Her Majesty's Stationery Office (HMSO) to enable information providers in the public sector to license the use and re-use of their information under a common open licence.

It is designed to encourage use and re-use of information freely and flexibly, with only a few conditions.