Skip to content

Latest commit

 

History

History
149 lines (101 loc) · 10.6 KB

README.md

File metadata and controls

149 lines (101 loc) · 10.6 KB
Raw

Gatsby site for CKS

Static website for NICE Clinical Knowledge Summaries (CKS) built with Gatsby and React

🚀 Jump straight to getting started

Table of contents

Stack

Software

If you're new to Gatsby, don't worry: it's a well used static site generator build with React and its documentation and community is superb.

Tests

We use Jest for JS unit testing with React Testing Library within the Gatsby static site.

To run the tests:

  1. cd gatsby in a terminal to get into the gatsby folder
  2. Run npm test to run the jest tests
    1. Or, run npm run test:watch to run the tests and watch for changes to files, to re-run the tests
    2. Or, run npm run test:coverage to run the tests and output a coverage folder with an lcov report.

Running tests in watch mode via npm run test:watch is most useful when developing locally.

If you prefer to run (and debug) the tests via an IDE (VS Code), then read on:

Debugging tests

We've configured 3 launch configurations (see .vscode/launch.json) for running and debugging Jest test:

  1. Jest tests (all) - runs all test, with a debugger attached
  2. Jest tests (current file) - runs the Jest against the file currently opened file.
  3. Jest tests (watch current file) - runs the Jest against the file currently opened file and watches for changes.

Run these from the 'Run and Debug' panel (Ctrl+Shift+D) in VS Code:

  1. Choose the relevent launch configuration from the menu
  2. Press the green play button (or press F5).

Note: these launch configurations are based on Microsoft's "Debugging tests in VS Code" recipe.

Why not Enzyme?

(And why React Testing Library instead?)

The NICE Digital Architecture Forum previously approved use of Enzyme as part of our front-end tech stack, and it's used within a few projects.

However, Enzyme is set up in a way to focus on internals of React components (props/state) rather than the DOM and what users end up seeing. So we like the philosophy of React Testing Library and subscribe to the guiding principle:

The more your tests resemble the way your software is used, the more confidence they can give you.

🚀 Set up

The easiest way to run the Gatsby site is via the Launch CKS debug command in VS Code. This is because it runs the other parts of the project too, not just the Gatsby site. See the readme in the repository root for more info.

However, to run the the Gatsby site on its own from the command line:

  1. Install Node 10+ (latest LTS version)
  2. Clone this repository
  3. Open the root of the repository in VS Code
  4. Install dependencies from npm:
    1. Run 'npm: Install Dependencies' from the VS Code command palette (Ctrl+Shift+P)
    2. Or run cd gatsby && npm ci on the command line
  5. Press F5 to build the gatsby site and debug in Chrome
    1. This uses the debugging built into VS Code
    2. Alternatively:
      1. run npm start from the gatsby folder
      2. open http://localhost:8000 in a browser

Other commands

There are various other commands you can run in a terminal from the gatsby folder:

Script What does it do
npm start Runs the Gatsby site in development mode
npm run build Builds the production build of the Gatsby site into the public folder. Note: the fake-api needs to be running else it won't build
npm run serve Serves the built Gatsby files from npm run build on http://localhost:9000/
npm run cb Copies useful Gatsby info to the clipboard, useful for reporting defects on GitHub
npm test Runs Jest tests
npm run test:watch Runs Jest tests and watches for file changes to re-run tests
npm run test:coverage Runs Jest tests and outputs coverage
npm run lint Runs prettier, eslint and typechecking
npm run prettier Checks files for codeformatting issues using Prettier
npm run prettier:fix Runs prettier and fixes any code formatting issues
npm run lint:ts Lints TypeScript and Javacript files using ESLint
npm run lint:ts:fix Fixes any linting errors using ESLint
npm run typecheck Typechecks the TypeScript files

Source plugin

Gatsby sites get their data via source plugins. Source plugins fetch data from somewhere (e.g. an API, database, filesystem etc) and turn them into Gatsby nodes. These nodes can then be queried via GraphQL inside Gatsby React components. Follow part 5 of the Gatsby tutorial ('Source Plugins') if you're new to sourcing data in Gatsby.

In the case of CKS, the source data comes from the API provided by Clarity. The data fetching and mapping to Gatsby nodes is handled via a custom source plugin. This gives a nice separation of the data loading logic from the page generation logic. The Gatsby docs has a useful section on 'Sourcing from Private APIs'.

View the custom source plugin (gatsby-source-cks) folder for more information.

Configuration

The source plugin can be configured by passing in options via gatsby-config.js. See the source plugin readme for details of each option.

Configure these options via environment variables. The Gatsby build looks for the following environment variables corresponding to each plugin option:

Config option Environment variable Notes
apiBaseUrl API_BASE_URL Leave blank to default to the local fake API at http://localhost:7000/api
apiKey API_KEY Leave blank to default to abc123 for the local fake API
changesSinceDate CHANGES_SINCE Date from which to load changes for the what's new page. Leave blank to default to the start of the previous month

Set these environment variables using .env files. Create a .env.development file (for local development with npm run develop) or .env.production file (for the production build with npm run build) in this gatsby folder to set these environment variables.

These .env files are deliberately ignore from git.

For example, create a .env.production file pointing to the live API to create a live-like production build via npm run build:

# .env.production
API_KEY=xyzetc
API_BASE_URL=https://whatever
CHANGES_SINCE=2020-05-01

Note: you can get the live API key and URL from the TeamCity build parameters or ask a team member.

TeamCity configuration

Use the Run Custom Build dialog in TeamCity to trigger a custom build and override CHANGES_SINCE environment variable. This can be useful at the end of the month to test the feed with a one-off build, where normally it would use the start of the previous month. Set the Changes since date on the Parameters tab within Run Custom Build to override the date.