@jisc/jisc-react-components NPM

React UI components

A library of components based on React and Material UI that are re-usable.

This library is designed to help React developers create UI components that are accessible, usable, and conforms to Jisc branding guidelines.

Project contents

The base project jisc-react-components is the component library that can be installed by the end users (eg developers working a React website).
A playground project where developers of this project can test components.
Storybook server
Terraform intrastructure code in the terraform/ directory

Local set up for developers

Pre-requisites

Node v14.x

Yarn v1.22.x

Recommended developer set-up

IDE: Visual Studio Code

Plugins:

Prettier: by installing this and enabling format on save, the code will automatically be formatted with the included Prettier config file. To enable auto format in VSCode:
- Install the Prettier plugin
- In your IDE, press CMD + SHIFT + P (you should get a pop-up with a greater than sign >)
- Type in "preferences" and select "Preferences: Open settings (JSON)"
- Ensure that the following fields are set:

"editor.defaultFormatter": "esbenp.prettier-vscode"

 "[javascript]": {
    "editor.formatOnSave": true
  }

"editor.formatOnSave": true

Bear in mind that Prettier works as well with some other editors. If the editor that you are using is not supported, please run yarn format.

Set up the component library jisc-react-components

Clone the repository: git clone git@github.com:JiscSD/jisc-react-components.git
cd jisc-react-components
Ensure your Node version and yarn versions correspond to the pre-requisies above
yarn install

Additional commands

These should be run in the root directory of the jisc-react-components directory

yarn start builds the library and watches for updates to then re-build
yarn check-format checks whether the files are formatted correctly
yarn format formats all files according to the prettier config
yarn test runs lint, build, and unit tests including coverage
yarn test:build tests whether the project is able to build correctly
yarn test:ci runs tests designed for the continuous integration pipeline, including lint, build, prettier, unit tests, and test coverage
yarn test:coverage runs the unit tests and coverage to check how much of the code is covered by unit tests
yarn test:lint runs the lint test
yarn test:unit runs the unit tests whilst watching for changes
yarn storybook starts the storybook server
yarn test:vreg runs the visual regression tests
yarn vreg-approve approves the current status of visual regression tests

Set up the playground application

From the root directory of jisc-react-components then cd playground
yarn install
yarn start

Visual Regression

Prerequisites:

Make sure you have the latest packages installed by running: yarn install in the base folder.
Have docker daemon running how to install docker

The codebuild pipeline will run on every commit pushed to remote on AWS, but if you need to run it locally you can:

Run yarn test:vreg
Check the .loki folder to see if there were any differences (tests will fail if this happens).

Approving the diferences:

You should have run the visual regression test as stated above first.
If you're happy with the changes in the difference folder just run yarn test:vreg-approve that will update the reference files.
Run yarn test:vreg and see how all the visual regression tests pass now.
Commit the updated reference files to git.

For more information about Loki you can check their documentation page.

On the pull request you can see the visual regression pipeline on every commit as seen here jisc-ui-loki:

You can see the generated report at https://jisc-ui-loki.s3.eu-west-1.amazonaws.com/pr/PR_ID_NUMBER/report.html (replace PR_ID_NUMBER in the url)

Usage

Install the following packages:

// If using yarn
yarn add @fortawesome/fontawesome-svg-core @fortawesome/free-solid-svg-icons @fortawesome/react-fontawesome @material-ui/core

// If using npm
npm install @fortawesome/fontawesome-svg-core @fortawesome/free-solid-svg-icons @fortawesome/react-fontawesome @material-ui/core

Basic example:

import { JiscThemeProvider, PageHeader } from '@jisc/jisc-react-components';

function App() {
  return (
    <JiscThemeProvider>
      <PageHeader title="Hello world" />
    </JiscThemeProvider>
  );
}

export  default  App;

Developing components

Git Hooks

This project uses git hooks configured by using the npm package called husky algonside lint-staged. This means that every time you commit code to the repository some scripts/actions will be fired before letting you commit, if any of them fail, the commit will be discarded. These are:

On Commit (yarn test):
- On the staged files (yarn lint-staged):
  - Linting all the codebase with ESLint
  - Formatting the codebase with prettier
- Build the library (yarn test:build)
- Audit the dependencies (yarn audit)
- Run all the tests + coverage (yarn test:coverage)
On Push: N/A