@statisticsnorway/cra-template-dapla-react-app v0.3.1

cra-template-dapla-react-app

This little template can be used as a cra-template when creating new React Applications. Basing a new project on a cra-template can be quite powerful and lets you skip the boring part of new project setup. Following the official documentation on templates for React, this template offers a good start for any React application built for Statistics Norway Data Platform (Dapla).

How to set it up?

From npm

yarn create react-app [app-name] --template @statisticsnorway/dapla-react-app

E.g. yarn create react-app new-dapla-app --template @statisticsnorway/dapla-react-app

Locally

1. Clone this repository
2. Create your new React application by running yarn create react-app [app-name] --template file:[path-to-this-repository]

For example, if you want to start a new project called new-dapla-app, and you cloned this repository to /Users/me/Projects/react-templates/cra-template-dapla-react-app, the command would be yarn create react-app new-dapla-app --template file:/Users/me/Projects/react-templates/cra-template-dapla-react-app.

Things to remember

Even though this type of setup for a new project skips a lot of configuration and setup there are still some small things you have to change and/or add in your new project.

First, some important properties are still missing from the package.json-file in your newly created project, and should be added:

• A description
• Link to the repository through repository
• An author
• A license where you specify the one from the licenses array

These are all included in the template.json file found in this repository but cra-templates for React is not quite at the level of copying every property from the template yet.

Secondly, some things need to be changed:

• In azure-pipelines.yml change the variable value for appName to your applications name
• In public/index.html change:
  • content in <meta name="description" />
  • <title>
• In public/manifest.json change short_name and name
• Insert your library name (GitHub repository name) after sonar.projectKey=statisticsnorway_ in sonar-project.properties

Lastly:

• Change REACT_APP_API in the .env-file

Phew! Now you should be good to go!

Another thing you might want to consider is moving the @testing-library libraries and the @beam-australia/react-env library from dependencies to devDependencies in your new project (in the package.json file). The template should have done this for you but at the moment cra-templates does not support declaring devDependencies in a template.

Publish cra-template library

To publish to npm you need a user and a membership in the statisticsnorway organization on npm. The user must also have 2FA authentication enabled. Steps to follow:

1. Login into your npm account in the terminal with npm login
2. Make sure all tests works (test components in the example application as well, if you made a new one)
3. Bump version in package.json
4. Dry run a release with npm pack
5. Publish with npm publish --access public --otp=<code> (<code> is your 2FA code, without <>)

Under the hood

So, what does this template actually give you?

• It pre-installs some dependencies, mainly:
  • @beam-australia/react-env enabling setting environment variables with docker run
  • axios through axios-hooks
  • PrimeReact
  • dapla-js-utilities
  • React
• Sets up CI for React applications with Azure Pipelines on BIP
  • Configures a Dockerfile
  • Configures serving the application with NGINX
  • Configures SonarCloud test coverage reporting
• Sets up a skeleton application with:
  • Context capabilities for language choice across the application and a backend api to talk to

General React setup

• Getting started
  • What you need
  • Preferred dependencies (tips)
  • Writing tests
  • Try this application locally
  • Docker locally
• More things
  • Environment variables
  • Runtime environment variables
  • React application as a library
• Deployment
  • SonarCloud
  • Dockerfile
  • Azure Pipelines (.azure-pipelines.yml)

Getting started

What you need

When creating a React application you need the following installed:

• JavaScript runtime Node.js (Use Current version)
• Dependency manager Yarn (Use Stable version)
• Use standardJS for code formatting (find your text editor plugin)

Use yarn create react-app [my-app] when creating new applications (almost everything is then setup for you). Replace [my-app] with the name of your application. If you want a more complete and preconfigured project setup for you there is the possibility to use cra-templates:

• For JavaScript library go to https://github.com/statisticsnorway/cra-template-dapla-js-lib

Preferred dependencies (tips)

• When working with routes in your application, use React Router
• When styling the UI, use PrimeReact
• When working with http-requests, use axios and axios-hooks
• Need to generate valid RFC UUIDs? Use uuid
• When writing tests, use Jest (comes pre-installed when creating application) and React Testing Library
• Need a simple GraphQL client? Check out graphql-request
  • Alternatively try a more rich hooks variant graphql-hooks

Writing tests

Easy to follow guides for Jest are located here and if you need to test DOM manipulation, use React Testing Library (guides found here). The debug property exposed by React Testing Library is very useful so do yourself a favor and check it out!

Test coverage thresholds and other options can be configured in the jest object in package.json, documentation found here. Something to keep in mind would be to exclude files like index.js, or files that only use external libraries. Mainly because these types of files do not need to be tested, but also because they may contribute to inaccurate coverage reporting.

CI=true yarn coverage exits with code 1 if thresholds are not met (those set in package.json) and thus will not result in a successful test run.

Check out the tests written in this application to get you started if you need some ideas.

Running any React application locally

The first time you clone the repository, remember to run yarn or yarn install.

Run yarn start and navigate to http://localhost:3000/.

yarn test runs all tests and yarn coverage calculates (rather unreliably) test coverage.

Docker locally

• yarn build
• docker build -t app-name .
• docker run -p 8000:8180 app-name:latest
  • Alternatively with custom environment variables: docker run -p 8000:8180 -e REACT_APP_API=http://localhost:9091 app-name:latest
• Navigate to http://localhost:8000/

More things

Environment variables

Simply follow the great documentation provided by the React developers.

Runtime environment variables

There is documentation on this and even an importable component called @beam-australia/react-env which you can try out.

Note about using @beam-australia/react-env. If you want to maintain control over your Docker image with things such as your own nginx.conf and you do not want to package @beam-australia/react-env with your application you can do it the way it is done in this project. Basically this means you have to:

• Write your own docker-entrypoint.sh file which uses @beam-australia/react-env in the same way they use it in their provided Docker image
• Refer to your environment variables with window.__ENV instead of @beam-australia/react-env's built-in env function.

Another caveat to using @beam-australia/react-env (or your own scripts to do the same thing) is that nodejs, yarn and @beam-australia/react-env, or something equivalent that can run scripts and build the __ENV.js file, have to be present in the Docker image. Which unfortunately makes the final application image not so slim after all. Additionally, this makes the Docker build step in the pipeline a little slower, which is only adding time to an already slow pipeline.

You can read about the issues surrounding runtime environment variables in React applications on the React GitHub page, issue 2353. This is where @beam-australia/react-env, and some other solutions are mentioned.

React application as a library

Requires some configuration and bundling with rollup.js. One such library is dapla-js-utilities and another is ssb-components-library. These can be used as examples for how to set it up correctly. Or you can use the template mentioned under Getting started - What you need.

Deployment

You can read all about it in the SSB developer guide , but in essence the .azure-pipelines.yml file needs to be configured as per instructed at the bottom of this README. The Docker-tasks in the mergeToMaster job is responsible for pushing the image to GCR.

You can check running builds here https://dev.azure.com/statisticsnorway.

SonarCloud

You can include a code analysis in the pipeline by adding the SonarCloud-tasks in the mergeToMaster job. For SonarCloud to work properly with JavaScript code you need some additional configuration found in the sonar-project.properties file. sonar.coverage.exclusions needs to mirror your settings in the jest property in package.json. Everything else set in the file is just standard exclusions.

Dockerfile

The reason for copying over our own nginx.conf is for it to work with React Router and provide a /health endpoint.

The /health endpoint is added so one can check for liveness and readiness of the Nginx serving the application. For now, they are equal but maybe in the future readiness will check for liveness of the application's integration points.

Azure Pipelines (azure-pipelines.yml)

The setup should be fairly easy by just following this applications .azure-pipelines.yml structure and remember to replace application name in the variable appName. Currently, we make use of templates for the pipeline, so the setup for new projects should be very straightforward.

Unfortunately we cannot run steps or tasks in parallel, but we have tried to make the pipeline as short as possible by separating a build and test job for pull requests and a build and push Docker job for merges to master.