React template

TODO: Replace the above heading with the project name.

Using this template

Search for TODO across the project to customise the template to a specific project.

TODO: Change the name field of the package.json and run npm install to update the package-lock.json.

TODO: Remove this section when all TODOs are resolved.

Technical overview

This project is built with TypeScript and Next.js.

We use:

• styled-jsx for styling components
• Normalize.css to normalize styles across browsers
• Docker to deploy and run the service
• Jest, Cucumber, and Selenium WebDriver for building and running tests
• ESLint for linting
• Prettier for code formatting

Dependencies

• Node.js

  We assume you are using the version of Node.js documented in .node-version. We recommend using nodenv with node-build-update-defs to manage Node.js versions.

• Google Chrome or Firefox

  We use these for running feature tests locally.

Getting started

1. Install the required packages:

   npm install

2. Run the development server:

   npm run dev

3. Navigate to http://localhost:3000.

Running the tests

We use Jest for testing. Feature tests are driven by Selenium Webdriver to test in browser.

To run the unit tests:

npm run test:unit

To run the unit tests, updating changed snapshots:

npm run test:unit:update

To run the unit tests in watch mode:

npm run test:unit:watch

To run the feature tests:

npm run test:feature

To run the feature tests, updating changed snapshots:

npm run test:feature:update

To run the feature tests in watch mode:

npm run test:feature:watch

To run the full test suite:

npm run test:all

To run the full test suite, updating changed snapshots:

npm run test:all:update

To run the full test suite, including format checking and linting:

npm test

To run the full test suite, including format checking and linting, fixing any issues and updating snapshots:

npm run test:update

Browser support

We support running the feature tests in Google Chrome and Firefox, headless or not.

The following environment variables customize the browser options for testing:

• TEST_BROWSER determines the browser to use.

  Accepted values:

  • chrome (default)
  • firefox

• TEST_HEADLESS determines if we run the browser in headless mode or not.

  Accepted values:

  • 0 for off
  • 1 for on (default)

Docker support

We support running the feature tests against a Docker image instead of a local server. Note that everything other than the feature tests that use Selenium WebDriver will always run on the host system.

The following environment variables customize the Docker options for testing:

• TEST_DOCKER_IMAGE (required) determines the Docker image to run against.

  You must have already built or pulled the image.

To run the feature tests:

npm run test:feature:docker

To run the full test suite:

npm run test:all:docker

To run the full test suite, including format checking and linting:

npm run test:docker

Formatting the code

We use Prettier to format our code. There are lots of editor integrations available, and the style is enforced by a Git pre-commit hook.

To run the formatter:

npm run format

Linting the code

We use ESLint, in addition to TypeScript's compiler, for verifying correctness and maintainability of code.

To run the linter:

npm run lint

To run the linter in fix mode:

npm run lint:fix

Architecture decision records

We use ADRs to document architecture decisions that we make. They can be found in docs/adr and contributed to with adr-tools.

Access

TODO: Document how people can find the service and its different environments.

Source

This repository was bootstrapped from dxw's react-template.