React 16 Migration Guide

Terra Core components have been uplifted to be compatible with React 16. Major versions of all the packages inside terra-core have been released to indicate the packages now depend on React 16 instead of React 15.

It is recommended that teams updating to the newly released the terra-core packages which rely on React 16 check out the official React 16 blog post from Facebook: https://reactjs.org/blog/2017/09/26/react-v16.0.html

Noted Changes

While most of the changes from React 15 to React 16 are passive, there were a few areas to take note of while uplifting.

• React 16 requires requestAnimationFrame. This means consumer will need to add the raf polyfill to work with legacy IE browsers.
• React 16 removes [data-reactroot] from the React Element.
• React 16 does not render portals correctly with enzyme.
  • Given our test coverage with nightwatch and wdio covered these cases, we opted just to remove the render tests.
  • If you were testing this behavior in your apps, it is recommended to test rendering portals with another with a test tool like wdio instead of enzyme.
• The updated terra-datepicker uses popper.js instead of tether.js for it's implementation.
• For our portal usage, we now use the new api available in React 16 as opposed to the legacy one, as indicated by the new imports.
• The focusable attribute on SVG nodes takes a string as opposed to a boolean for it's value.
• In React 16, HTML attributes are more strict.
  • Before, if you had a boolean attribute on an HTML element, it would convert a JavaScript boolean value to a string value. With React 16, you must pass a string value.
  • With React 15, you could set aria-require={false}.
  • With React 16, you would want to set that as aria-required="false"

Uplifting your application

To uplift your app to use the new terra-core components which now use React 16, the following steps should be implemented:

Application Code

• Update all of your terra-core packages to the latest released major versions.
• Uplift any react or react-dom dependencies in any of your package.json.
  • react: "^16.2.0"
  • react-dom: "^16.2.0"
• If using terra-icon, change the focusable prop on any icons to a string (<Icon focusable="true" />).
• If you are using react-portal, ensure you are using the latest API instead of the legacy one. For most cases, that will mean switching import Portal from 'react-portal' to import { Portal } from 'react-portal'.

Jest Tests

• In React 16, the context of a React component is no longer automatically populated when using shallow or mount. If you need to test the context, either declare a context in the second argument of the shallow or mount method, or switch to the render method.
• For the React 16 enzyme adapter, the render method throws heap memory exceptions if you are running render on a component that uses a portal. For our case, we relied on our nightwatch and wdio tests to test the scenarios where we had to test a fully rendered component with a portal. Related issue

WDIO Tests

• Uplift your terra-toolkit dependency to >= 2.7.0.
• In React 16, [data-reactroot] was removed from the react components. We used this selector previously to take a screenshot of a WDIO test. To account for this change, implement the following:
  • Create a base test wrapper with an id like in this commit.
  • Add a terra.selector value to the wdio.conf.js file like in this commit.
  • This will solve most of the tests, but there maybe tests where you need to change the value of the selector. Examples of doing this can be found here and here.
  • For some tests, you may need to add an additional wrapper with styles like in this one
  • We can't predict all the possible issues that occur, so further work could potentially need to be done to ensure your snapshot tests are accurate.