App

Upstand FM web application.

• Create React App
• Storybook
• Tests
• CI/CD
• Configuration
• Design

Create React App

This project was bootstrapped with Create React App (CRA).

• Available scripts
• Code linting
• Code formatting
• Additional resources

Available scripts

In the project directory, you can run:

npm start

Runs the app in the development mode.
Open http://localhost:3000 to view it in the browser.

The page will reload if you make edits.
You will also see any lint errors in the console.

Make sure you have created a configuration file first.

npm test

Launches the test runner in the interactive watch mode.
See the section about running tests for more information.

npm run build

Builds the app for production to the build folder.
It correctly bundles React in production mode and optimizes the build for the best performance.

The build is minified and the filenames include the hashes.

See the section about deployment for more information.

npm run eject

Note: this is a one-way operation. Once you eject, you can’t go back!

If you aren’t satisfied with the build tool and configuration choices, you can eject at any time. This command will remove the single build dependency from your project.

Instead, it will copy all the configuration files and the transitive dependencies (Webpack, Babel, ESLint, etc) right into your project so you have full control over them. All of the commands except eject will still work, but they will point to the copied scripts so you can tweak them. At this point you’re on your own.

You don’t have to ever use eject. The curated feature set is suitable for small and middle deployments, and you shouldn’t feel obligated to use this feature. However we understand that this tool wouldn’t be useful if you couldn’t customize it when you are ready for it.

npm run cy

Runs end-to-end tests locally using Cypress.

Caveats:

• The local dev server must be running (use npm start), before the end-to-end tests can run.
• The watch-and-reload plugin is used to rerun tests on source code change. But according to this issue, this functionality will be native in the future. When that's the case, remove the plugin.

npm run sb

Starts the Storybook locally.

This may (but doesn't have to) run together with npm start and/or npm test.

npm run sb:build

Builds the Storybook as a static website, so it can be deployed.

Code linting

CRA default ESLint settings are used, but are extended with a custom .eslintrc.json file. For example to add Cypress globals.

Code formatting

Code is automatically formatted on commit with Prettier.

Additional resources

• Code splitting
• Analyzing the bundle size
• Making a Progressive Web App
• Advanced configuration
• Deployment
• npm run build fails to minify
• Create React App documentation
• React documentation

Storybook

Storybook is used to help build components (component driven development), document component APIs/usage, and test components.

Storybook files are colocated with the implementation files. For example, the component Button.jsx will have a Storybook file named Button.stories.jsx in the same dir.

A live Storybook can be found at upstand-fm-storybook.netlify.app.

Tests

Unit & integration

The React Testing Library is used together with Testing Library Jest DOM to write unit- & integration tests.

Test files are colocated with the implementation files. For example, the component Button.jsx will have a test file named Button.spec.jsx in the same dir.

Integration & end-to-end

Cypress is used to run integration- & end-to-end tests, and records them.

The recorded test runs can be viewed here. The logs are public, but you need a Cypress account view them.. 🤣

Test files can be found in /cypress/integration.

Visual regression testing

Percy is used for visually testing/reviewing changes made to components. This is done by taking "snapshots" of components and "diffing" them, whenever a GitHub Pull Request is made.

Percy has been setup together with Storybook, so it captures each story.

The builds/snapshots are public and can be viewed here.

CI/CD

CircleCI is used to:

• Audit npm dependencies for security vulnerabilities.
• Run unit/integration tests (Jest).
• Run integration/end-to-end tests (Cypress).
• Build Storybook and app
• Run visual regression tests
• Deploy Storybook and app via Netlify

Testing

Cypress

CircleCI requires a Cypress token to record tests and store screenshots.

The token can be found in the Cypress dashboard under "Record Keys". It is configured in CircleCI as an environment variable named CYPRESS_RECORD_KEY, and used in the .circleci/config.yml file.

Percy

CircleCI requires a Percy token to take- and "diff" snapshots.

The token can be found in the Percy dashboard under "Project Token". It is configured in CircleCI as an environment variable named PERCY_TOKEN, and automatically used by the percy-storybook binary.

Netlify

CircleCI requires a Netlify access token, site ID and publish directory to deploy the built files (Storybook + app). These are configured as environment variables:

Token

The Netlify access token can be found in the 1Password "Upstand FM" vault under "Netlify access token for CircleCI".

The token is configured in CircleCI as an environment variable named NETLIFY_ACCESS_TOKEN.

Site ID

There are 2 site IDs (Storybook + app) and their values are configured as env vars:

Type	Description	Env var name	Netlify UI link
Storybook	The component website at upstand-fm-storybook.netlify.app.	NETLIFY_SB_SITE_ID	upstand-fm-storybook/settings
App	The web app, at upstand-fm-app.netlify.app.	NETLIFY_SITE_ID	upstand-fm-app/settings

Note that the Netlify site ID is named "API ID" in the Netlify web app. And can be found under Settings > General > Site Details > Site Information.

Publish directory

There are 2 publish directories (Storybook + app) and their values are configured as env vars:

Type	Description	Build command	Publish directory	Env var name
Storybook	The component website at upstand-fm-storybook.netlify.app.	npm run sb:build	build-storybook	STORYBOOK_BUILD_DIR
App	The web app, at upstand-fm-app.netlify.app.	npm run build	build	NETLIFY_PUBLISH_DIR

Note that the publish directory is the "output" of running one of the build commands. A publish directory contains the files that Netlify must deploy.

Configuration

The app is configured via .env files:

• .env.development is the config required to run the app locally.
• .env.production is the config required to run the app in production.

Note that these files should NOT (and do not) contain secrets!

Both files must contain the following environment variables:

Name	Required	Description
REACT_APP_AUTH0_DOMAIN	Yes	The Auth0 tenant domain name.
REACT_APP_AUTH0_CLIENT_ID	Yes	The application client ID as configured in Auth0.
REACT_APP_AUTH0_REDIRECT_URI	Yes	Set to http://localhost:3000 for dev. And https://upstand-fm-app.netlify.app for prod.
REACT_APP_AUTH0_LOGOUT_URL	Yes	Should match the REACT_APP_AUTH0_REDIRECT_URI value.
REACT_APP_AUTH0_AUDIENCE	Yes	The audience for which the issued token is intended. Set this to https://api.upstand.fm.
REACT_APP_AUTH0_SCOPE	Yes	The OAuth scopes that are requested on behalf of the user. And which are "evaluated" by the "audience".

Caveats

• You must create custom environment variables beginning with REACT_APP_.
• Any other variables except NODE_ENV will be ignored to avoid accidentally exposing a private key on the machine that could have the same name.
• You have to restart the dev server after changing the .env.development file.

Design

Logo & color scheme

See the design assets for more info.

Fonts

Fira Sans is used:

• Regular (400)
• Bold (600)

They can be found in src/fonts.