Upgrading to React 18.3.1

[jack-ryan-nava-pbc]

What even is React?

React is the core Javascript framework that supports our Design System. Our components are constructed using it's APIs and it is the foundation upon which our system rests.

Currently the Design System uses React version 17.0.2. With the release of React 19 recently we are now two major versions behind. We also received a number of questions from product teams who are interested in adopting newer versions of React. Migrating to React 18.3.1 would offer our team a number of benefits:

1. Act as a stepping stone to version 19
2. Highlight deprecated or soon to be deprecated APIs that we will need to replace
3. Offer built in utilities that we can take advantage of over third party options (looking at you, useId)

Plan of action

We have 4 main dependencies that monitor the React version:

1. React itself
2. react-app-polyfill
3. react-dom
4. react-test-renderer

These will need to be upgraded in sequence and merged into a feature branch so that we can avoid test failures on CI when we go to merge the whole thing in.

Pull request sequence:

1. react, react-dom & react-app-polyfill upgrade (polyfills might not need upgrading)
2. Because our Design System does not use the ReactDOM.render method and it's replacement in version 18.3.1 (createRoot) this upgrade will just work. We will be able to build and use the Design System without issue. However, tests will fail because they do use the ReactDOM.render method. So we need to upgrade our test runners.
3. Upgrade react-test-renderer to 18.3.1 to take advantage of new rendering engine in tests
4. Upgrade @testing-library-react to 16.1.0 - Note this is the latest version, but I figured just go for it rather than incrementally upgrade. Upgrading to 13.0.0 which is the version of testing-library-react that first accepts version 18 encounters other issues.
5. In tandem with the upgrade to @testing-library-react 16.1.0, we can make the following changes:
   • Remove all mentions of @testing-library/react-hooks as this package is built in now 🪅
   • Replace places where we import renderHook with: import { renderHook } from '@testing-library/react'
   • We can probably change our import statement in our tests to this import { render, screen, act, renderHook } from '@testing-library/react'; in most cases

Consequences

For product teams

Most of our product teams are using version 17 or 18 of React. Our migration to React 18.3.1 should not affect compatibility, but we need to make sure. We have two astro-based example folders that serve as test cases, one is running React 18, and the other is running React 17. Each pull from a shared folder of components built with whatever version of React the design system is using. If either package fails to render properly, then we know we have an issue.

That said, we still want to make sure we are not messing things up for product teams. Product teams, if you're reading this, please let us know what you think in our slack channel

For the design system

React 18.3.1 will allow us to identify and start to remove places where we use defaultProps. We will also have the opportunity to rethink our testing strategy more broadly. We have had some internal conversations around moving away from JSDOM and towards a more ecologically valid testing option, possibly through Vitest or Playwright. There may be some issues with JSDOM that must be addressed as a result of this upgrade. See this ticket for more information as we uncover a path forward.

The Future

This is an exciting change to the Design System that will allow us to mitigate several sources of tech debt, reduce the number of needed dependencies and to reduce seemingly stochastic test failures (useId again...). It will also position us well to begin the work of examining the migration to React 19, which has many more substantial API changes.

[jack-ryan-nava-pbc]

I want to note here that additional work for us centers around updating our Gatsby instance to v5 which utilizes React v18.

This will require us to update our MDX plugin from v3 to v4 following this guide. This will be non-trivial work.