Node Web-app Template

Overview

The following repo allows us to quickly bootstrap Node projects, using this allows us to ensure consistency across our Node repositories. It can be a starting point for the creation of RESTful API ​or for the creation of web application with GOV.UK Design System best practice.

In the context of a web application, each page or user interface, defined by an endpoint, is divided into three components (MVC) and as a best practice the names for the model, view and controller have, when possible, the same start name of the endpoints (e.g. for the /info page we have the: info.controller.ts and info.html files. If models were present, we would have info.model.ts)

The Model

In the model we define the interface, the data structure used to represent the data for that particular page and an array used to map back and forth information between the data saved and the nunjucks html view data.

The View

We use Nunjucks and GDS style/components, we could use the prototype if an UX team is present in loco.

The Controller

Generally only POST and GET http methods are allowed, and therefore we will have mainly just the get and post controllers, and it is literally the last successful middleware of the chain that has the duty to respond to the user. In the get method we fetch possible data and pass it to the view/template to be visualized to the user and in the post method we save the user data everytime that a page is submitted

Files Structure

Directory Path	Description
./.github	Github folder, includes PULL_REQUEST_TEMPLATE.md on how to make a pull request to the project and dependabot.yml configuration options for dependency updates.
./.husky	Add pre check script, includes pre-commit and pre-push checks
./src	Contains all TypeScript code
./src/app.ts	Application entry point
./src/config/index.ts	Contains all the application's configurations
./src/controller	Business logic and handlers
./src/middleware	Middleware functions (Authentication, validation ...)
./src/model	OE Session and View Data Model
./src/routes	Paths and routes controller (Only GET and POST enabled)
./src/service	Interface to the API through SDK
./src/utils	Facade for CO services (e.g. logging) and other application utils (navigation, application data ...)
./src/validation	Sets of express validator middlewares for each page
./test	Jest Test files (*.spec.ts, setup.ts, and *.mocks.ts)
./view	Contains all the html nunjucks structure files
./docs	Contains documentation files
Others files	Other files related to modules dependency, CI/CD, *git, dockerization, lint, test/typescript configs …

Config variables

Some config variables relate to authentication, refer to node-login for more details about how these variables are used.

Key	Description	Example Value
AUTH_SIGN_IN_URL	Authentication # URL	https://cola.service.cabinetoffice.gov.uk/v2/<YOUR_SERVICE>/#
BASE_URL	Base application URL	http://localhost:3000 (dev mode)
CDN_HOST	CDN host	cdn_domain
COOKIE_ID_NAME	The name of the COLA authentication cookie	github-requests
COOKIE_PARSER_SECRET	Secret used in validating/calculating the cookie signature	secret
COOKIE_SESSION_SECRET	Secret key for signing the session cookie	secret
HUMAN	Formatting messages form (default JSON)	true (Enable human formatting for log messages)
LOG_LEVEL	Logging levels	info
NODE_ENV	Node environment	development or production
NODE_SSL_ENABLED	Node SSL	true or false
PATH_SSL_CERTIFICATE	Path to SSL certificate	./infrastructure/host/test.cert
PATH_SSL_PRIVATE_KEY	Path to SSL private key	./infrastructure/host/test.key
PORT	Server port number	3000
SESSION_APP_KEY	Session application key	git
SESSION_ID_NAME	Session ID name	connect.sid
USER_POOL_CLIENT_ID	Client ID of an app registered with the user pool in Amazon Cognito	secret
USER_POOL_ID	ID of the user pool in Amazon Cognito	secret

ESlint

We use ESlint as both a formatter and code quality assurance. Eslint can also be setup to format on save using a VScode extension:

1. Install the ESlint VScode extenstion.
2. Open your user settings (JSON) inside VScode and add the following:

    "editor.formatOnSave": true, 
    "editor.codeActionsOnSave": { "source.fixAll.eslint": true }

3. Reload VScode.

Running local development environment with Docker

Docker is used run the application in development mode, with tooling setup to detect changes in local src directory and reload the container's node server.

Follow the steps in Launching-the-web-app, and ensure that NODE_ENV=development is set in the .env file.

Launching the web-app

Prerequisites

1. Install NodeJS V20.8

2. Install Docker

Building the Docker Image

1. Create a copy of the .env.example file and name it .env:

Then run:

make docker-build

make docker-up

This will then download the necessary dependencies, build the Docker image, and start the application. You will be able to access it on localhost:3000.

ToDo

• Add API service module
• Add Validation and Navigation MW
• Add Authentication MW and Session handler logic
• Update CDN origin
• Publishes the SDK on npm package registry