Static website for NICE Clinical Knowledge Summaries (CKS) built with Gatsby and React
🚀 Jump straight to getting started
Table of contents
- VS Code IDE
- With recommended extensions (VS Code will prompt you to install these automatically)
Gatsby and Preact for static site generationNote: we use Preact as a 'drop in' replacement via gatsby-plugin-preact because it's smaller and faster than ReactUPDATE: Can't use Preact when upgrading to React v18 as Preact hasn't been updated to support the features of React v18 yet.
- TypeScript for static type checking
- Prettier for code formatting
- ESLint for JavaScript/TypeScripting linting
- Jest for JS unit testing
- node-fetch for loading data
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.
We use Jest for JS unit testing with React Testing Library within the Gatsby static site.
To run the tests:
cd gatsby
in a terminal to get into the gatsby folder- Run
npm test
to run the jest tests- Or, run
npm run test:watch
to run the tests and watch for changes to files, to re-run the tests - Or, run
npm run test:coverage
to run the tests and output a coverage folder with an lcov report.
- Or, run
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:
We've configured 3 launch configurations (see .vscode/launch.json) for running and debugging Jest test:
- Jest tests (all) - runs all test, with a debugger attached
- Jest tests (current file) - runs the Jest against the file currently opened file.
- 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:
- Choose the relevent launch configuration from the menu
- Press the green play button (or press F5).
Note: these launch configurations are based on Microsoft's "Debugging tests in VS Code" recipe.
(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.
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:
- Install Node 10+ (latest LTS version)
- Clone this repository
- Open the root of the repository in VS Code
- Install dependencies from npm:
- Run 'npm: Install Dependencies' from the VS Code command palette (Ctrl+Shift+P)
- Or run
cd gatsby && npm ci
on the command line
- Press F5 to build the gatsby site and debug in Chrome
- This uses the debugging built into VS Code
- Alternatively:
- run
npm start
from the gatsby folder - open http://localhost:8000 in a browser
- run
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 |
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.
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.
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.