Creating GOV.UK styled React applications with govuk-react-jsx

The Coronavirus dashboard from Public Health England in action

The Coronavirus dashboard from Public Health England has used components which were recently open sourced by Surevine. They were developed in order to support a recent government project Surevine worked on which required us to build a GOV.UK styled React app adhering to the GOV.UK Design System. After evaluating the current open source options for this, we opted to create a new library, and as a result we created govuk-react-jsx on GitHub, published to govuk-react-jsx on npmjs.com.

A demo is also available at https://surevine.github.io/govuk-react-jsx/

​Our goals for the project were that it should:

Directly consume the govuk-frontend package

​By exactly replicating the govuk-frontend HTML and directly consuming the govuk-frontend CSS and JavaScript we ensure:

  • GDS’ effort to develop accessible markup patterns is maintained since we replicate the components exactly. Aria attributes are present. The attention to detail in the govuk-frontend codebase is exemplary and we wanted to keep all that good work.
  • Upstream changes to the CSS/JS can be brought in simply by changing a version number.
  • Upstream changes to HTML are simple ports from Nunjucks to JSX – by following through the govuk-frontend changelog (Massive kudos to the design system team for keeping such a thorough changelog – it is invaluable!).
  • Be as unopinionated as possible

​We can’t know all the different ways people are going to use this, so we wanted to keep to the simplest and least opinionated solutions. This meant sticking with compiling the Sass from upstream govuk-frontend rather than choosing to go with a CSS-in-JS option common in the React world. (I concede, this is an opinion in of itself!)

Be simple to maintain

​The other principle we wanted to adhere to was for the library to be as simple to maintain as possible. When open source becomes a chore, it ceases to be sustainable. Open source burnout is a real problem.

​In order to achieve this, significant effort has gone into making the test suite do all the heavy lifting of assuring that the port is true to the original. By rendering a set of example data through the original Nunjucks reference implementation and comparing it with the React output we are able to effectively remove human error from the equation when it comes to assuring the port is accurate. When a new release from govuk-frontend is pulled in – the test suite fails and shows you exactly which aspects of the HTML need changing. Cross referencing these test failures with the govuk-frontend changelog means that we can be sure beyond reasonable doubt that the port is accurate.

Conclusion

​If you’re looking to create a GOV.UK styled React app we hope you will consider using this library. If you encounter any issues or have questions you can raise an issue on Github and we will do our best to help out.