grants-config-feature-controls

Core delivery platform Node.js Backend Template.

• Grant Configuration
  • Create new
  • Update existing
  • Non-configuration changes
  • Hotfix release
• Requirements
  • Node.js
• Local development
  • Setup
  • Development
  • Testing
  • Production
  • Npm scripts
  • Update dependencies
  • Formatting
    • Windows prettier issue
• API endpoints
• Development helpers
  • MongoDB Locks
  • Proxy
• Docker
  • Development image
  • Production image
  • Docker Compose
  • Dependabot
  • SonarCloud
• Licence
  • About the licence

Each directory within the configurations folder represents a separate grant.

To create a new grant:

1. Create a new directory under configurations, for example:

   configurations/playground
   

2. Add at least one configuration file, for example:

   configurations/playground/slide-config/main.json
   

3. Create a new version:

   npm run version

4. Stage and commit your changes using the standard commit format:

   git add .
   git commit -m "feat(YOUR-TICKET): YOUR-MESSAGE"

5. Push your branch and then follow the standard GitHub pull request process.

   git push

To update the configuration for an existing grant:

1. Add or modify the required configuration files.

2. Create a new version:

   npm run version

3. Stage and commit your changes:

   git add .
   git commit -m "feat(YOUR-TICKET): YOUR-MESSAGE"

4. Push your branch and then follow the standard GitHub pull request process.

   git push

Any change that does not modify the contents of the configurations directory is considered a non-configuration change.

Do not create a changeset for these changes. Non-configuration changes do not trigger service publication when merged into main.

Hotfix releases should only be used as a last resort when a fix cannot be delivered through the normal release process because subsequent releases contain incompatible changes.

Important: Changes made on a hotfix branch are not automatically included in future releases. After publishing the hotfix, apply the same changes to main to ensure they are included in the next release.

Hotfix releases can only increment the patch version of an existing release.

If a hotfix is required, complete the following steps:

1. Create a hotfix branch from the tagged release version that requires the fix. For example, the following command creates a hotfix-releases/6.3.x branch from the 6.3.0 tag:

   git fetch --tags
   git switch -c hotfix-releases/6.3.x tags/6.3.0

2. Make the required configuration changes.

3. Create a new patch version:

   npm run version

4. Stage, commit, and push your changes.

5. Manually run the Publish Hot Fix GitHub workflow.

   Note: This workflow only runs on branches with the hotfix-releases/ prefix.

   The workflow will:

   • Publish the new patch version.
   • Remove the generated changeset file.

   The workflow requires a description input, which is used as part of the workflow run name.

Please install Node.js >= v24 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 grants-config-feature-controls
nvm use

Install application dependencies:

npm install

Install git hooks (optional)

npm run git:hooks

To run the application in development mode run:

npm run dev

To test the application run:

npm run test

To mimic the application running in production mode locally run:

npm start

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

npm run

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

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

If you require a write lock for Mongo you can acquire it via server.locker or request.locker:

async function doStuff(server) {
  const lock = await server.locker.lock('unique-resource-name')

  if (!lock) {
    // Lock unavailable
    return
  }

  try {
    // do stuff
  } finally {
    await lock.free()
  }
}

Keep it small and atomic.

You may use using for the lock resource management. Note test coverage reports do not like that syntax.

async function doStuff(server) {
  await using lock = await server.locker.lock('unique-resource-name')

  if (!lock) {
    // Lock unavailable
    return
  }

  // do stuff

  // lock automatically released
}

Helper methods are also available in /src/helpers/mongo-lock.js.

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
  })
})

Build:

docker build --no-cache --tag grants-config-feature-controls .

Run:

docker run -e PORT=3001 -p 3001:3001 grants-config-feature-controls

A local environment with:

• MongoDB
• This service.

docker compose up --build -d

Mock AWS resources can be created when Floci starts up by editing the scripts in ./compose/floci/start.d/. MongoDB records can also be created when Mongo starts by editing the scripts in ./compose/mongo/.

Dependabot is enabled in this repository.

SonarCloud is enabled in this repository.

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

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.