Here’s the video courtesy of JSConf Iceland:

I think you’ll enjoy the talk more if you stop reading here and just watch the video. If you don’t have time to watch, a (very) brief summary follows.

About the Two Demos

On the first demo, Dan says: “We’ve built a generic way to ensure that high-priority updates don’t get blocked by a low-priority update, called time slicing. If my device is fast enough, it feels almost like it’s synchronous; if my device is slow, the app still feels responsive. It adapts to the device thanks to the requestIdleCallback API. Notice that only the final state was displayed; the rendered screen is always consistent and we don’t see visual artifacts of slow rendering causing a janky user experience.”

On the second demo, Dan explains: “We’ve built a generic way for components to suspend rendering while they load async data, which we call suspense. You can pause any state update until the data is ready, and you can add async loading to any component deep in the tree without plumbing all the props and state through your app and hoisting the logic. On a fast network, updates appear very fluid and instantaneous without a jarring cascade of spinners that appear and disappear. On a slow network, you can intentionally design which loading states the user should see and how granular or coarse they should be, instead of showing spinners based on how the code is written. The app stays responsive throughout.”

“Importantly, this is still the React you know. This is still the declarative component paradigm that you probably like about React.”

We can’t wait to release these new async rendering features later this year. Follow this blog and @reactjs on Twitter for updates.

While these changes helped us make React better, they don’t affect most React users directly. However, we hope that blogging about them might help other library authors solve similar problems. Our contributors might also find these notes helpful!

Formatting Code with Prettier

React was one of the first large repositories to fully embrace opinionated automatic code formatting with Prettier. Our current Prettier setup consists of:

• A local yarn prettier script that uses the Prettier Node API to format files in place. We typically run it before committing changes. It is fast because it only checks the files changed since diverging from remote master.
• A script that runs Prettier as part of our continuous integration checks. It won’t attempt to overwrite the files, but instead will fail the build if any file differs from the Prettier output for that file. This ensures that we can’t merge a pull request unless it has been fully formatted.

Some team members have also set up the editor integrations. Our experience with Prettier has been fantastic, and we recommend it to any team that writes JavaScript.

Restructuring the Monorepo

Ever since React was split into packages, it has been a monorepo: a set of packages under the umbrella of a single repository. This made it easier to coordinate changes and share the tooling, but our folder structure was deeply nested and difficult to understand. It was not clear which files belonged to which package. After releasing React 16, we’ve decided to completely reorganize the repository structure. Here is how we did it.

Migrating to Yarn Workspaces

The Yarn package manager introduced a feature called Workspaces a few months ago. This feature lets you tell Yarn where your monorepo’s packages are located in the source tree. Every time you run yarn, in addition to installing your dependencies it also sets up the symlinks that point from your project’s node_modules to the source folders of your packages.

Thanks to Workspaces, absolute imports between our own packages (such as importing react from react-dom) “just work” with any tools that support the Node resolution mechanism. The only problem we encountered was Jest not running the transforms inside the linked packages, but we found a fix, and it was merged into Jest.

To enable Yarn Workspaces, we added "workspaces": ["packages/*"] to our package.json, and moved all the code into top-level packages/* folders, each with its own package.json file.

Each package is structured in a similar way. For every public API entry point such as react-dom or react-dom/server, there is a file in the package root folder that re-exports the implementation from the /src/ subfolder. The decision to point entry points to the source rather than to the built versions was intentional. Typically, we re-run a subset of tests after every change during development. Having to build the project to run a test would have been prohibitively slow. When we publish packages to npm, we replace these entry points with files in the /npm/ folder that point to the build artifacts.

Not all packages have to be published on npm. For example, we keep some utilities that are tiny enough and can be safely duplicated in a pseudo-package called shared. Our bundler is configured to only treat dependencies declared from package.json as externals so it happily bundles the shared code into react and react-dom without leaving any references to shared/ in the build artifacts. So you can use Yarn Workspaces even if you don’t plan to publish actual npm packages!

Removing the Custom Module System

In the past, we used a non-standard module system called “Haste” that lets you import any file from any other file by its unique @providesModule directive no matter where it is in the tree. It neatly avoids the problem of deep relative imports with paths like ../../../../ and is great for the product code. However, this makes it hard to understand the dependencies between packages. We also had to resort to hacks to make it work with different tools.

We decided to remove Haste and use the Node resolution with relative imports instead. To avoid the problem of deep relative paths, we have flattened our repository structure so that it goes at most one level deep inside each package:

|-react
|  |-npm
|  |-src
|-react-dom
|  |-npm
|  |-src
|  |  |-client
|  |  |-events
|  |  |-server
|  |  |-shared

This way, the relative paths can only contain one ./ or ../ followed by the filename. If one package needs to import something from another package, it can do so with an absolute import from a top-level entry point.

In practice, we still have some cross-package “internal” imports that violate this principle, but they’re explicit, and we plan to gradually get rid of them.

Compiling Flat Bundles

Historically, React was distributed in two different formats: as a single-file build that you can add as a <script> tag in the browser, and as a collection of CommonJS modules that you can bundle with a tool like webpack or Browserify.

Before React 16, each React source file had a corresponding CommonJS module that was published as part of the npm packages. Importing react or react-dom led bundlers to the package entry point from which they would build a dependency tree with the CommonJS modules in the internal lib folder.

However, this approach had multiple disadvantages:

• It was inconsistent. Different tools produce bundles of different sizes for identical code importing React, with the difference going as far as 30 kB (before gzip).
• It was inefficient for bundler users. The code produced by most bundlers today contains a lot of “glue code” at the module boundaries. It keeps the modules isolated from each other, but increases the parse time, the bundle size, and the build time.
• It was inefficient for Node users. When running in Node, performing process.env.NODE_ENV checks before development-only code incurs the overhead of actually looking up environment variables. This slowed down React server rendering. We couldn’t cache it in a variable either because it prevented dead code elimination with Uglify.
• It broke encapsulation. React internals were exposed both in the open source (as react-dom/lib/* imports) and internally at Facebook. It was convenient at first as a way to share utilities between projects, but with time it became a maintenance burden because renaming or changing argument types of internal functions would break unrelated projects.
• It prevented experimentation. There was no way for the React team to experiment with any advanced compilation techniques. For example, in theory, we might want to apply Google Closure Compiler Advanced optimizations or Prepack to some of our code, but they are designed to work on complete bundles rather than small individual modules that we used to ship to npm.

Due to these and other issues, we’ve changed the strategy in React 16. We still ship CommonJS modules for Node.js and bundlers, but instead of publishing many individual files in the npm package, we publish just two CommonJS bundles per entry point.

For example, when you import react with React 16, the bundler finds the entry point that just re-exports one of the two files:

'use strict';

if (process.env.NODE_ENV === 'production') {
  module.exports = require('./cjs/react.production.min.js');
} else {
  module.exports = require('./cjs/react.development.js');
}

In every package provided by React, the cjs folder (short for “CommonJS”) contains a development and a production pre-built bundle for each entry point.

For example, react.development.js is the version intended for development. It is readable and includes comments. On the other hand, react.production.min.js was minified and optimized before it was published to npm.

Note how this is essentially the same strategy that we’ve been using for the single-file browser builds (which now reside in the umd directory, short for Universal Module Definition). Now we just apply the same strategy to the CommonJS builds as well.

Migrating to Rollup

Just compiling CommonJS modules into single-file bundles doesn’t solve all of the above problems. The really significant wins came from migrating our build system from Browserify to Rollup.

Rollup was designed with libraries rather than apps in mind, and it is a perfect fit for React’s use case. It solves one problem well: how to combine multiple modules into a flat file with minimal junk code in between. To achieve this, instead of turning modules into functions like many other bundlers, it puts all the code in the same scope, and renames variables so that they don’t conflict. This produces code that is easier for the JavaScript engine to parse, for a human to read, and for a minifier to optimize.

Rollup currently doesn’t support some features that are important to application builders, such as code splitting. However, it does not aim to replace tools like webpack that do a great job at this. Rollup is a perfect fit for libraries like React that can be pre-built and then integrated into apps.

You can find our Rollup build configuration here, with a list of plugins we currently use.

Migrating to Google Closure Compiler

After migrating to flat bundles, we started using the JavaScript version of the Google Closure Compiler in its “simple” mode. In our experience, even with the advanced optimizations disabled, it still provided a significant advantage over Uglify, as it was able to better eliminate dead code and automatically inline small functions when appropriate.

At first, we could only use Google Closure Compiler for the React bundles we shipped in the open source. At Facebook, we still needed the checked-in bundles to be unminified so we could symbolicate React production crashes with our error reporting tools. We ended up contributing a flag that completely disables the renaming compiler pass. This lets us apply other optimizations like function inlining, but keep the code fully readable for the Facebook-specific builds of React. To improve the output readability, we also format that custom build using Prettier. Interestingly, running Prettier on production bundles while debugging the build process is a great way to find unnecessary code in the bundles!

Currently, all production React bundles run through Google Closure Compiler in simple mode, and we may look into enabling advanced optimizations in the future.

Protecting Against Weak Dead Code Elimination

While we use an efficient dead code elimination solution in React itself, we can’t make a lot of assumptions about the tools used by the React consumers.

Typically, when you configure a bundler for production, you need to tell it to substitute process.env.NODE_ENV with the "production" string literal. This process is sometimes called “envification”. Consider this code:

if (process.env.NODE_ENV !== "production") {
  // development-only code
}

After envification, this condition will always be false, and can be completely eliminated by most minifiers:

if ("production" !== "production") {
  // development-only code
}

However, if the bundler is misconfigured, you can accidentally ship development code into production. We can’t completely prevent this, but we took a few steps to mitigate the common cases when it happens.

Protecting Against Late Envification

As mentioned above, our entry points now look like this:

'use strict';

if (process.env.NODE_ENV === 'production') {
  module.exports = require('./cjs/react.production.min.js');
} else {
  module.exports = require('./cjs/react.development.js');
}

However, some bundlers process requires before envification. In this case, even if the else block never executes, the cjs/react.development.js file still gets bundled.

To prevent this, we also wrap the whole content of the development bundle into another process.env.NODE_ENV check inside the cjs/react.development.js bundle itself:

'use strict';

if (process.env.NODE_ENV !== "production") {
  (function() {
    // bundle code
  })();
}

This way, even if the application bundle includes both the development and the production versions of the file, the development version will be empty after envification.

The additional IIFE wrapper is necessary because some declarations (e.g. functions) can’t be placed inside an if statement in JavaScript.

Detecting Misconfigured Dead Code Elimination

Even though the situation is changing, many popular bundlers don’t yet force the users to specify the development or production mode. In this case process.env.NODE_ENV is typically provided by a runtime polyfill, but the dead code elimination doesn’t work.

We can’t completely prevent React users from misconfiguring their bundlers, but we introduced a few additional checks for this in React DevTools.

If the development bundle executes, React DOM reports this to React DevTools:

There is also one more bad scenario. Sometimes, process.env.NODE_ENV is set to "production" at runtime rather than at the build time. This is how it should work in Node.js, but it is bad for the client-side builds because the unnecessary development code is bundled even though it never executes. This is harder to detect but we found a heuristic that works well in most cases and doesn’t seem to produce false positives.

We can write a function that contains a development-only branch with an arbitrary string literal. Then, if process.env.NODE_ENV is set to "production", we can call toString() on that function and verify that the string literal in the development-only has been stripped out. If it is still there, the dead code elimination didn’t work, and we need to warn the developer. Since developers might not notice the React DevTools warnings on a production website, we also throw an error inside setTimeout from React DevTools in the hope that it will be picked up by the error analytics.

We recognize this approach is somewhat fragile. The toString() method is not reliable and may change its behavior in future browser versions. This is why we put that logic into React DevTools itself rather than into React. This allows us to remove it later if it becomes problematic. We also warn only if we found the special string literal rather than if we didn’t find it. This way, if the toString() output becomes opaque, or is overridden, the warning just won’t fire.

Catching Mistakes Early

We want to catch bugs as early as possible. However, even with our extensive test coverage, occasionally we make a blunder. We made several changes to our build and test infrastructure this year to make it harder to mess up.

Migrating to ES Modules

With the CommonJS require() and module.exports, it is easy to import a function that doesn’t really exist, and not realize that until you call it. However, tools like Rollup that natively support import and export syntax fail the build if you mistype a named import. After releasing React 16, we have converted the entire React source code to the ES Modules syntax.

Not only did this provide some extra protection, but it also helped improve the build size. Many React modules only export utility functions, but CommonJS forced us to wrap them into an object. By turning those utility functions into named exports and eliminating the objects that contained them, we let Rollup place them into the top-level scope, and thus let the minifier mangle their names in the production builds.

For now, have decided to only convert the source code to ES Modules, but not the tests. We use powerful utilities like jest.resetModules() and want to retain tighter control over when the modules get initialized in tests. In order to consume ES Modules from our tests, we enabled the Babel CommonJS transform, but only for the test environment.

Running Tests in Production Mode

Historically, we’ve been running all tests in a development environment. This let us assert on the warning messages produced by React, and seemed to make general sense. However, even though we try to keep the differences between the development and production code paths minimal, occasionally we would make a mistake in production-only code branches that weren’t covered by tests, and cause an issue at Facebook.

To solve this problem, we have added a new yarn test-prod command that runs on CI for every pull request, and executes all React test cases in the production mode. We wrapped any assertions about warning messages into development-only conditional blocks in all tests so that they can still check the rest of the expected behavior in both environments. Since we have a custom Babel transform that replaces production error messages with the error codes, we also added a reverse transformation as part of the production test run.

Using Public API in Tests

When we were rewriting the React reconciler, we recognized the importance of writing tests against the public API instead of internal modules. If the test is written against the public API, it is clear what is being tested from the user’s perspective, and you can run it even if you rewrite the implementation from scratch.

We reached out to the wonderful React community asking for help converting the remaining tests to use the public API. Almost all of the tests are converted now! The process wasn’t easy. Sometimes a unit test just calls an internal method, and it’s hard to figure out what the observable behavior from user’s point of view was supposed to be tested. We found a few strategies that helped with this. The first thing we would try is to find the git history for when the test was added, and find clues in the issue and pull request description. Often they would contain reproducing cases that ended up being more valuable than the original unit tests! A good way to verify the guess is to try commenting out individual lines in the source code being tested. If the test fails, we know for sure that it stresses the given code path.

We would like to give our deepest thanks to everyone who contributed to this effort.

Running Tests on Compiled Bundles

There is also one more benefit to writing tests against the public API: now we can run them against the compiled bundles.

This helps us ensure that tools like Babel, Rollup, and Google Closure Compiler don’t introduce any regressions. This also opens the door for future more aggressive optimizations, as we can be confident that React still behaves exactly as expected after them.

To implement this, we have created a second Jest config. It overrides our default config but points react, react-dom, and other entry points to the /build/packages/ folder. This folder doesn’t contain any React source code, and reflects what gets published to npm. It is populated after you run yarn build.

This lets us run the same exact tests that we normally run against the source, but execute them using both development and production pre-built React bundles produced with Rollup and Google Closure Compiler.

Unlike the normal test run, the bundle test run depends on the build products so it is not great for quick iteration. However, it still runs on the CI server so if something breaks, the test will display as failed, and we will know it’s not safe to merge into master.

There are still some test files that we intentionally don’t run against the bundles. Sometimes we want to mock an internal module or override a feature flag that isn’t exposed to the public yet. For those cases, we blacklist a test file by renaming it from MyModule-test.js to MyModule-test.internal.js.

Currently, over 93% out of 2,650 React tests run against the compiled bundles.

Linting Compiled Bundles

In addition to linting our source code, we run a much more limited set of lint rules (really, just two of them) on the compiled bundles. This gives us an extra layer of protection against regressions in the underlying tools and ensures that the bundles don’t use any language features that aren’t supported by older browsers.

Simulating Package Publishing

Even running the tests on the built packages is not enough to avoid shipping a broken update. For example, we use the files field in our package.json files to specify a whitelist of folders and files that should be published on npm. However, it is easy to add a new entry point to a package but forget to add it to the whitelist. Even the bundle tests would pass, but after publishing the new entry point would be missing.

To avoid situations like this, we are now simulating the npm publish by running npm pack and then immediately unpacking the archive after the build. Just like npm publish, this command filters out anything that isn’t in the files whitelist. With this approach, if we were to forget adding an entry point to the list, it would be missing in the build folder, and the bundle tests relying on it would fail.

Creating Manual Test Fixtures

Our unit tests run only in the Node environment, but not in the browsers. This was an intentional decision because browser-based testing tools were flaky in our experience, and didn’t catch many issues anyway.

We could get away with this because the code that touches the DOM is consolidated in a few files, and doesn’t change that often. Every week, we update the Facebook.com codebase to the latest React commit on master. At Facebook, we use a set of internal WebDriver tests for critical product workflows, and these catch some regressions. React updates are first delivered to employees, so severe bugs get reported immediately before they reach two billion users.

Still, it was hard to review DOM-related changes, and occasionally we would make mistakes. In particular, it was hard to remember all the edge cases that the code had to handle, why they were added, and when it was safe to remove them. We considered adding some automatic tests that run in the browser but we didn’t want to slow down the development cycle and deal with a fragile CI. Additionally, automatic tests don’t always catch DOM issues. For example, an input value displayed by the browser may not match what it reports as a DOM property.

We’ve chatted about this with Brandon Dail, Jason Quense, and Nathan Hunzaker. They were sending substantial patches to React DOM but were frustrated that we failed to review them timely. We decided to give them commit access, but asked them to create a set of manual tests for DOM-related areas like input management. The initial set of manual fixtures kept growing over the year.

These fixtures are implemented as a React app located in fixtures/dom. Adding a fixture involves writing a React component with a description of the expected behavior, and links to the appropriate issues and browser quirks, like in this example:

The fixture app lets you choose a version of React (local or one of the published versions) which is handy for comparing the behavior before and after the changes. When we change the behavior related to how we interact with the DOM, we can verify that it didn’t regress by going through the related fixtures in different browsers.

In some cases, a change proved to be so complex that it necessitated a standalone purpose-built fixture to verify it. For example, the DOM attribute handling in React 16 was very hard to pull off with confidence at first. We kept discovering different edge cases, and almost gave up on doing it in time for the React 16 release. However, then we’ve built an “attribute table” fixture that renders all supported attributes and their misspellings with previous and next version of React, and displays the differences. It took a few iterations (the key insight was to group attributes with similar behavior together) but it ultimately allowed us to fix all major issues in just a few days.

We went through the table to vet the new behavior for every case (and discovered some old bugs too) pic.twitter.com/cmF2qnK9Q9

— Dan Abramov (@dan_abramov) September 8, 2017

Going through the fixtures is still a lot of work, and we are considering automating some of it. Still, the fixture app is invaluable even as documentation for the existing behavior and all the edge cases and browser bugs that React currently handles. Having it gives us confidence in making significant changes to the logic without breaking important use cases. Another improvement we’re considering is to have a GitHub bot build and deploy the fixtures automatically for every pull request that touches the relevant files so anyone can help with browser testing.

Preventing Infinite Loops

The React 16 codebase contains many while loops. They let us avoid the dreaded deep stack traces that occurred with earlier versions of React, but can make development of React really difficult. Every time there is a mistake in an exit condition our tests would just hang, and it took a while to figure out which of the loops is causing the issue.

Inspired by the strategy adopted by Repl.it, we have added a Babel plugin that prevents infinite loops in the test environment. If some loop continues for more than the maximum allowed number of iterations, we throw an error and immediately fail it so that Jest can display where exactly this happened.

This approach has a pitfall. If an error thrown from the Babel plugin gets caught and ignored up the call stack, the test will pass even though it has an infinite loop. This is really, really bad. To solve this problem, we set a global field before throwing the error. Then, after every test run, we rethrow that error if the global field has been set. This way any infinite loop will cause a test failure, no matter whether the error from the Babel plugin was caught or not.

Customizing the Build

There were a few things that we had to fine-tune after introducing our new build process. It took us a while to figure them out, but we’re moderately happy with the solutions that we arrived at.

Dead Code Elimination

The combination of Rollup and Google Closure Compiler already gets us pretty far in terms of stripping development-only code in production bundles. We replace the __DEV__ literal with a boolean constant during the build, and both Rollup together and Google Closure Compiler can strip out the if (false) {} code branches and even some more sophisticated patterns. However, there is one particularly nasty case:

import warning from 'fbjs/lib/warning';

if (__DEV__) {
  warning(false, 'Blimey!');
}

This pattern is very common in the React source code. However fbjs/lib/warning is an external import that isn’t being bundled by Rollup for the CommonJS bundle. Therefore, even if warning() call ends up being removed, Rollup doesn’t know whether it’s safe to remove to the import itself. What if the module performs a side effect during initialization? Then removing it would not be safe.

To solve this problem, we use the treeshake.pureExternalModules Rollup option which takes an array of modules that we can guarantee don’t have side effects. This lets Rollup know that an import to fbjs/lib/warning is safe to completely strip out if its value is not being used. However, if it is being used (e.g. if we decide to add warnings in production), the import will be preserved. That’s why this approach is safer than replacing modules with empty shims.

When we optimize something, we need to ensure it doesn’t regress in the future. What if somebody introduces a new development-only import of an external module, and not realize they also need to add it to pureExternalModules? Rollup prints a warning in such cases but we’ve decided to fail the build completely instead. This forces the person adding a new external development-only import to explicitly specify whether it has side effects or not every time.

Forking Modules

In some cases, different bundles need to contain slightly different code. For example, React Native bundles have a different error handling mechanism that shows a redbox instead of printing a message to the console. However, it can be very inconvenient to thread these differences all the way through the calling modules.

Problems like this are often solved with runtime configuration. However, sometimes it is impossible: for example, the React DOM bundles shouldn’t even attempt to import the React Native redbox helpers. It is also unfortunate to bundle the code that never gets used in a particular environment.

Another solution is to use dynamic dependency injection. However, it often produces code that is hard to understand, and may cause cyclical dependencies. It also defies some optimization opportunities.

From the code point of view, ideally we just want to “redirect” a module to its different “forks” for specific bundles. The “forks” have the exact same API as the original modules, but do something different. We found this mental model very intuitive, and created a fork configuration file that specifies how the original modules map to their forks, and the conditions under which this should happen.

For example, this fork config entry specifies different feature flags for different bundles:

'shared/ReactFeatureFlags': (bundleType, entry) => {
  switch (entry) {
    case 'react-native-renderer':
      return 'shared/forks/ReactFeatureFlags.native.js';
    case 'react-cs-renderer':
      return 'shared/forks/ReactFeatureFlags.native-cs.js';
    default:
      switch (bundleType) {
        case FB_DEV:
        case FB_PROD:
          return 'shared/forks/ReactFeatureFlags.www.js';
      }
  }
  return null;
},

During the build, our custom Rollup plugin replaces modules with their forks if the conditions have matched. Since both the original modules and the forks are written as ES Modules, Rollup and Google Closure Compiler can inline constants like numbers or booleans, and thus efficiently eliminate dead code for disabled feature flags. In tests, when necessary, we use jest.mock() to point the module to the appropriate forked version.

As a bonus, we might want to verify that the export types of the original modules match the export types of the forks exactly. We can use a slightly odd but totally working Flow trick to accomplish this:

import typeof * as FeatureFlagsType from 'shared/ReactFeatureFlags';
import typeof * as FeatureFlagsShimType from './ReactFeatureFlags.native';
type Check<_X, Y: _X, X: Y = _X> = null;
(null: Check<FeatureFlagsShimType, FeatureFlagsType>);

This works by essentially forcing Flow to verify that two types are assignable to each other (and thus are equivalent). Now if we modify the exports of either the original module or the fork without changing the other file, the type check will fail. This might be a little goofy but we found this helpful in practice.

To conclude this section, it is important to note that you can’t specify your own module forks if you consume React from npm. This is intentional because none of these files are public API, and they are not covered by the semver guarantees. However, you are always welcome to build React from master or even fork it if you don’t mind the instability and the risk of divergence. We hope that this writeup was still helpful in documenting one possible approach to targeting different environments from a single JavaScript library.

Tracking Bundle Size

As a final build step, we now record build sizes for all bundles and write them to a file that looks like this. When you run yarn build, it prints a table with the results:

(It doesn’t always look as good as this. This was the commit that migrated React from Uglify to Google Closure Compiler.)

Keeping the file sizes committed for everyone to see was helpful for tracking size changes and motivating people to find optimization opportunities.

We haven’t been entirely happy with this strategy because the JSON file often causes merge conflicts on larger branches. Updating it is also not currently enforced so it gets out of date. In the future, we’re considering integrating a bot that would comment on pull requests with the size changes.

Simplifying the Release Process

We like to release updates to the open source community often. Unfortunately, the old process of creating a release was slow and would typically take an entire day. After some changes to this process, we’re now able to do a full release in less than an hour. Here’s what we changed.

Branching Strategy

Most of the time spent in the old release process was due to our branching strategy. The master branch was assumed to be unstable and would often contain breaking changes. Releases were done from a stable branch, and changes were manually cherry-picked into this branch prior to a release. We had tooling to help automate some of this process, but it was still pretty complicated to use.

As of version 16, we now release from the master branch. Experimental features and breaking changes are allowed, but must be hidden behind feature flags so they can be removed during the build process. The new flat bundles and dead code elimination make it possible for us to do this without fear of leaking unwanted code into open source builds.

Automated Scripts

After changing to a stable master, we created a new release process checklist. Although much simpler than the previous process, this still involved dozens of steps and forgetting one could result in a broken release.

To address this, we created a new automated release process that is much easier to use and has several built-in checks to ensure that we release a working build. The new process is split into two steps: build and publish. Here’s what it looks like the first time you run it:

The build step does most of the work- verifying permissions, running tests, and checking CI status. Once it finishes, it prints a reminder to update the CHANGELOG and to verify the bundle using the manual fixtures described above.

All that’s left is to tag and publish the release to NPM using the publish script.

(You may have noticed a --dry flag in the screenshots above. This flag allows us to run a release, end-to-end, without actually publishing to NPM. This is useful when working on the release script itself.)

In Conclusion

Did this post inspire you to try some of these ideas in your own projects? We certainly hope so! If you have other ideas about how React build, test, or contribution workflow could be improved, please let us know on our issue tracker.

You can find the related issues by the build infrastructure label. These are often great first contribution opportunities!

Acknowledgements

We would like to thank:

• Rich Harris and Lukas Taegert for maintaining Rollup and helping us integrate it.
• Dimitris Vardoulakis, Chad Killingsworth, and Tyler Breisacher for their work on Google Closure Compiler and timely advice.
• Adrian Carolli, Adams Au, Alex Cordeiro, Jordan Tepper, Johnson Shi, Soo Jae Hwang, Joe Lim, Yu Tian, and others for helping prototype and implement some of these and other improvements.
• Anushree Subramani, Abid Uzair, Sotiris Kiritsis, Tim Jacobi, Anton Arboleda, Jeremias Menichelli, Audy Tanudjaja, Gordon Dent, Iacami Gevaerd , Lucas Lentz, Jonathan Silvestri, Mike Wilcox, Bernardo Smaniotto, Douglas Gimli, Ethan Arrowood, and others for their help porting the React test suite to use the public API.

Inspired by Yarn, Ember, and Rust, the goal is to allow React core team members and community members to collaborate on the design of new features. It’s also intended to provide a clear path for ideas to enter the project:

• Create an RFC document detailing your proposal.
• Submit a PR to the RFC repository.
• Incorporate feedback into the proposal.
• After discussion, the core team may or may not accept the RFC.
• If the RFC is accepted, the PR is merged.

RFCs are accepted when they are approved for implementation in React. A more thorough description of the process is available in the repository’s README. The exact details may be refined in the future.

Who Can Submit RFCs?

Anyone! No knowledge of React’s internals is required, nor are you expected to implement the proposal yourself.

As with our other repositories, we do ask that you complete a Contributor License Agreement before we can accept your PR.

What Types of Changes Should Be Submitted As RFCs?

Generally, any idea that would benefit from additional review or design before being implemented is a good candidate for an RFC. As a rule of thumb, this means any proposal that adds, changes, or removes a React API.

Not every change must go through the RFC process. Bug fixes or performance improvements that don’t touch the API can be submitted directly to the main library.

We now have several repositories where you can submit contributions to React:

• Issues, bugfixes, and code changes to the main library: facebook/react
• Website and documentation: reactjs/reactjs.org
• Ideas for changes that need additional review before being implemented: reactjs/rfcs

RFC for A New Context API

Coinciding with the launch of our RFC process, we’ve submitted a proposal for a new version of context. The proposal has already received many valuable comments from the community that we will incorporate into the design of the new API.

The context PR is a good example of how a typical RFC should be structured. We’re excited to start receiving your proposals!

Fragments look like empty JSX tags. They let you group a list of children without adding extra nodes to the DOM:

render() {
  return (
    <>
      <ChildA />
      <ChildB />
      <ChildC />
    </>
  );
}

This exciting new feature is made possible by additions to both React and JSX.

What Are Fragments?

A common pattern is for a component to return a list of children. Take this example HTML:

Some text.
<h2>A heading</h2>
More text.
<h2>Another heading</h2>
Even more text.

Prior to version 16, the only way to achieve this in React was by wrapping the children in an extra element, usually a div or span:

render() {
  return (
    // Extraneous div element :(
    <div>
      Some text.
      <h2>A heading</h2>
      More text.
      <h2>Another heading</h2>
      Even more text.
    </div>
  );
}

To address this limitation, React 16.0 added support for returning an array of elements from a component’s render method. Instead of wrapping the children in a DOM element, you can put them into an array:

render() {
 return [
  "Some text.",
  <h2 key="heading-1">A heading</h2>,
  "More text.",
  <h2 key="heading-2">Another heading</h2>,
  "Even more text."
 ];
}

However, this has some confusing differences from normal JSX:

• Children in an array must be separated by commas.
• Children in an array must have a key to prevent React’s key warning.
• Strings must be wrapped in quotes.

To provide a more consistent authoring experience for fragments, React now provides a first-class Fragment component that can be used in place of arrays.

render() {
  return (
    <Fragment>
      Some text.
      <h2>A heading</h2>
      More text.
      <h2>Another heading</h2>
      Even more text.
    </Fragment>
  );
}

You can use <Fragment /> the same way you’d use any other element, without changing the way you write JSX. No commas, no keys, no quotes.

The Fragment component is available on the main React object:

const Fragment = React.Fragment;

<Fragment>
  <ChildA />
  <ChildB />
  <ChildC />
</Fragment>

// This also works
<React.Fragment>
  <ChildA />
  <ChildB />
  <ChildC />
</React.Fragment>

JSX Fragment Syntax

Fragments are a common pattern in our codebases at Facebook. We anticipate they’ll be widely adopted by other teams, too. To make the authoring experience as convenient as possible, we’re adding syntactical support for fragments to JSX:

render() {
  return (
    <>
      Some text.
      <h2>A heading</h2>
      More text.
      <h2>Another heading</h2>
      Even more text.
    </>
  );
}

In React, this desugars to a <React.Fragment/> element, as in the example from the previous section. (Non-React frameworks that use JSX may compile to something different.)

Fragment syntax in JSX was inspired by prior art such as the XMLList() <></> constructor in E4X. Using a pair of empty tags is meant to represent the idea it won’t add an actual element to the DOM.

Keyed Fragments

Note that the <></> syntax does not accept attributes, including keys.

If you need a keyed fragment, you can use <Fragment /> directly. A use case for this is mapping a collection to an array of fragments — for example, to create a description list:

function Glossary(props) {
  return (
    <dl>
      {props.items.map(item => (
        // Without the `key`, React will fire a key warning
        <Fragment key={item.id}>
          <dt>{item.term}</dt>
          <dd>{item.description}</dd>
        </Fragment>
      ))}
    </dl>
  );
}

key is the only attribute that can be passed to Fragment. In the future, we may add support for additional attributes, such as event handlers.

Live Demo

You can experiment with JSX fragment syntax with this CodePen.

Support for Fragment Syntax

Support for fragment syntax in JSX will vary depending on the tools you use to build your app. Please be patient as the JSX community works to adopt the new syntax. We’ve been working closely with maintainers of the most popular projects:

Create React App

Experimental support for fragment syntax will be added to Create React App within the next few days. A stable release may take a bit longer as we await adoption by upstream projects.

Babel

Support for JSX fragments is available in Babel v7.0.0-beta.31 and above! If you are already on Babel 7, simply update to the latest Babel and plugin transform:

# for yarn users
yarn upgrade @babel/core @babel/plugin-transform-react-jsx
# for npm users
npm update @babel/core @babel/plugin-transform-react-jsx

Or if you are using the react preset:

# for yarn users
yarn upgrade @babel/core @babel/preset-react
# for npm users
npm update @babel/core @babel/preset-react

Note that Babel 7 is technically still in beta, but a stable release is coming soon.

Unfortunately, support for Babel 6.x is not available, and there are currently no plans to backport.

Babel with Webpack (babel-loader)

If you are using Babel with Webpack, no additional steps are needed because babel-loader will use your peer-installed version of Babel.

Babel with Other Frameworks

If you use JSX with a non-React framework like Inferno or Preact, there is a pragma option available in babel-plugin-transform-react-jsx that configures the Babel compiler to de-sugar the <></> syntax to a custom identifier.

TypeScript

TypeScript has full support for fragment syntax! Please upgrade to version 2.6.2. (Note that this is important even if you are already on version 2.6.1, since support was added as patch release in 2.6.2.)

Upgrade to the latest TypeScript with the command:

# for yarn users
yarn upgrade typescript
# for npm users
npm update typescript

Flow

Flow support for JSX fragments is available starting in version 0.59! Simply run

# for yarn users
yarn upgrade flow-bin
# for npm users
npm update flow-bin

to update Flow to the latest version.

Prettier

Prettier added support for fragments in their 1.9 release.

ESLint

JSX Fragments are supported by ESLint 3.x when it is used together with babel-eslint:

# for yarn users
yarn add eslint@3.x babel-eslint@7
# for npm users
npm install eslint@3.x babel-eslint@7

or if you already have it, then upgrade:

# for yarn users
yarn upgrade eslint@3.x babel-eslint@7
# for npm users
npm update eslint@3.x babel-eslint@7

Ensure you have the following line inside your .eslintrc:

"parser": "babel-eslint"

That’s it!

Note that babel-eslint is not officially supported by ESLint. We’ll be looking into adding support for fragments to ESLint 4.x itself in the coming weeks (see issue #9662).

Editor Support

It may take a while for fragment syntax to be supported in your text editor. Please be patient as the community works to adopt the latest changes. In the meantime, you may see errors or inconsistent highlighting if your editor does not yet support fragment syntax. Generally, these errors can be safely ignored.

TypeScript Editor Support

If you’re a TypeScript user — great news! Editor support for JSX fragments is already available in Visual Studio 2015, Visual Studio 2017, Visual Studio Code and Sublime Text via Package Control.

Other Tools

For other tools, please check with the corresponding documentation to check if there is support available. However, if you’re blocked by your tooling, you can always start with using the <Fragment> component and perform a codemod later to replace it with the shorthand syntax when the appropriate support is available.

Installation

React v16.2.0 is available on the npm registry.

To install React 16 with Yarn, run:

yarn add react@^16.2.0 react-dom@^16.2.0

To install React 16 with npm, run:

npm install --save react@^16.2.0 react-dom@^16.2.0

We also provide UMD builds of React via a CDN:

<script crossorigin src="https://unpkg.com/react@16/umd/react.production.min.js"></script>
<script crossorigin src="https://unpkg.com/react-dom@16/umd/react-dom.production.min.js"></script>

Refer to the documentation for detailed installation instructions.

Changelog

React

• Add Fragment as named export to React. (@clemmy in #10783)
• Support experimental Call/Return types in React.Children utilities. (@MatteoVH in #11422)

React DOM

• Fix radio buttons not getting checked when using multiple lists of radios. (@landvibe in #11227)
• Fix radio buttons not receiving the onChange event in some cases. (@jquense in #11028)

React Test Renderer

• Fix setState() callback firing too early when called from componentWillMount. (@accordeiro in #11507)

React Reconciler

• Expose react-reconciler/reflection with utilities useful to custom renderers. (@rivenhk in #11683)

Internal Changes

• Many tests were rewritten against the public API. Big thanks to everyone who contributed!

Acknowledgments

This release was made possible by our open source contributors. A big thanks to everyone who filed issues, contributed to syntax discussions, reviewed pull requests, added support for JSX fragments in third party libraries, and more!

Special thanks to the TypeScript and Flow teams, as well as the Babel maintainers, who helped make tooling support for the new syntax go seamlessly.

Thanks to Gajus Kuizinas and other contributors who prototyped the Fragment component in open source.

New render return types: fragments and strings

You can now return an array of elements from a component’s render method. Like with other arrays, you’ll need to add a key to each element to avoid the key warning:

render() {
  // No need to wrap list items in an extra element!
  return [
    // Don't forget the keys :)
    <li key="A">First item</li>,
    <li key="B">Second item</li>,
    <li key="C">Third item</li>,
  ];
}

Starting with React 16.2.0, we are adding support for a special fragment syntax to JSX that doesn’t require keys.

We’ve added support for returning strings, too:

render() {
  return 'Look ma, no spans!';
}

See the full list of supported return types.

Better error handling

Previously, runtime errors during rendering could put React in a broken state, producing cryptic error messages and requiring a page refresh to recover. To address this problem, React 16 uses a more resilient error-handling strategy. By default, if an error is thrown inside a component’s render or lifecycle methods, the whole component tree is unmounted from the root. This prevents the display of corrupted data. However, it’s probably not the ideal user experience.

Instead of unmounting the whole app every time there’s an error, you can use error boundaries. Error boundaries are special components that capture errors inside their subtree and display a fallback UI in its place. Think of error boundaries like try-catch statements, but for React components.

For more details, check out our previous post on error handling in React 16.

Portals

Portals provide a first-class way to render children into a DOM node that exists outside the DOM hierarchy of the parent component.

render() {
  // React does *not* create a new div. It renders the children into `domNode`.
  // `domNode` is any valid DOM node, regardless of its location in the DOM.
  return ReactDOM.createPortal(
    this.props.children,
    domNode,
  );
}

See a full example in the documentation for portals.

Better server-side rendering

React 16 includes a completely rewritten server renderer. It’s really fast. It supports streaming, so you can start sending bytes to the client faster. And thanks to a new packaging strategy that compiles away process.env checks (Believe it or not, reading process.env in Node is really slow!), you no longer need to bundle React to get good server-rendering performance.

Core team member Sasha Aickin wrote a great article describing React 16’s SSR improvements. According to Sasha’s synthetic benchmarks, server rendering in React 16 is roughly three times faster than React 15. “When comparing against React 15 with process.env compiled out, there’s about a 2.4x improvement in Node 4, about a 3x performance improvement in Node 6, and a full 3.8x improvement in the new Node 8.4 release. And if you compare against React 15 without compilation, React 16 has a full order of magnitude gain in SSR in the latest version of Node!” (As Sasha points out, please be aware that these numbers are based on synthetic benchmarks and may not reflect real-world performance.)

In addition, React 16 is better at hydrating server-rendered HTML once it reaches the client. It no longer requires the initial render to exactly match the result from the server. Instead, it will attempt to reuse as much of the existing DOM as possible. No more checksums! In general, we don’t recommend that you render different content on the client versus the server, but it can be useful in some cases (e.g. timestamps). However, it’s dangerous to have missing nodes on the server render as this might cause sibling nodes to be created with incorrect attributes.

See the documentation for ReactDOMServer for more details.

Support for custom DOM attributes

Instead of ignoring unrecognized HTML and SVG attributes, React will now pass them through to the DOM. This has the added benefit of allowing us to get rid of most of React’s attribute whitelist, resulting in reduced file sizes.

Reduced file size

Despite all these additions, React 16 is actually smaller compared to 15.6.1!

• react is 5.3 kb (2.2 kb gzipped), down from 20.7 kb (6.9 kb gzipped).
• react-dom is 103.7 kb (32.6 kb gzipped), down from 141 kb (42.9 kb gzipped).
• react + react-dom is 109 kb (34.8 kb gzipped), down from 161.7 kb (49.8 kb gzipped).

That amounts to a combined 32% size decrease compared to the previous version (30% post-gzip).

The size difference is partly attributable to a change in packaging. React now uses Rollup to create flat bundles for each of its different target formats, resulting in both size and runtime performance wins. The flat bundle format also means that React’s impact on bundle size is roughly consistent regardless of how you ship your app, whether it’s with Webpack, Browserify, the pre-built UMD bundles, or any other system.

MIT licensed

In case you missed it, React 16 is available under the MIT license. We’ve also published React 15.6.2 under MIT, for those who are unable to upgrade immediately.

New core architecture

React 16 is the first version of React built on top of a new core architecture, codenamed “Fiber.” You can read all about this project over on Facebook’s engineering blog. (Spoiler: we rewrote React!)

Fiber is responsible for most of the new features in React 16, like error boundaries and fragments. Over the next few releases, you can expect more new features as we begin to unlock the full potential of React.

Perhaps the most exciting area we’re working on is async rendering—a strategy for cooperatively scheduling rendering work by periodically yielding execution to the browser. The upshot is that, with async rendering, apps are more responsive because React avoids blocking the main thread.

This demo provides an early peek at the types of problems async rendering can solve:

Ever wonder what "async rendering" means? Here's a demo of how to coordinate an async React tree with non-React work https://t.co/3snoahB3uV pic.twitter.com/egQ988gBjR

— Andrew Clark (@acdlite) September 18, 2017

Tip: Pay attention to the spinning black square.

We think async rendering is a big deal, and represents the future of React. To make migration to v16.0 as smooth as possible, we’re not enabling any async features yet, but we’re excited to start rolling them out in the coming months. Stay tuned!

Installation

React v16.0.0 is available on the npm registry.

To install React 16 with Yarn, run:

yarn add react@^16.0.0 react-dom@^16.0.0

To install React 16 with npm, run:

npm install --save react@^16.0.0 react-dom@^16.0.0

We also provide UMD builds of React via a CDN:

<script crossorigin src="https://unpkg.com/react@16/umd/react.production.min.js"></script>
<script crossorigin src="https://unpkg.com/react-dom@16/umd/react-dom.production.min.js"></script>

Refer to the documentation for detailed installation instructions.

Upgrading

Although React 16 includes significant internal changes, in terms of upgrading, you can think of this like any other major React release. We’ve been serving React 16 to Facebook and Messenger.com users since earlier this year, and we released several beta and release candidate versions to flush out additional issues. With minor exceptions, if your app runs in 15.6 without any warnings, it should work in 16.

For deprecations listed in packaging below, codemods are provided to automatically transform your deprecated code. See the 15.5.0 blog post for more information, or browse the codemods in the react-codemod project.

New deprecations

Hydrating a server-rendered container now has an explicit API. If you’re reviving server-rendered HTML, use ReactDOM.hydrate instead of ReactDOM.render. Keep using ReactDOM.render if you’re just doing client-side rendering.

React Addons

As previously announced, we’ve discontinued support for React Addons. We expect the latest version of each addon (except react-addons-perf; see below) to work for the foreseeable future, but we won’t publish additional updates.

Refer to the previous announcement for suggestions on how to migrate.

react-addons-perf no longer works at all in React 16. It’s likely that we’ll release a new version of this tool in the future. In the meantime, you can use your browser’s performance tools to profile React components.

Breaking changes

React 16 includes a number of small breaking changes. These only affect uncommon use cases and we don’t expect them to break most apps.

• React 15 had limited, undocumented support for error boundaries using unstable_handleError. This method has been renamed to componentDidCatch. You can use a codemod to automatically migrate to the new API.
• ReactDOM.render and ReactDOM.unstable_renderSubtreeIntoContainer now return null if called from inside a lifecycle method. To work around this, you can use portals or refs.

• setState:

  • Calling setState with null no longer triggers an update. This allows you to decide in an updater function if you want to re-render.
  • Calling setState directly in render always causes an update. This was not previously the case. Regardless, you should not be calling setState from render.
  • setState callbacks (second argument) now fire immediately after componentDidMount / componentDidUpdate instead of after all components have rendered.
• When replacing <A /> with <B />, B.componentWillMount now always happens before A.componentWillUnmount. Previously, A.componentWillUnmount could fire first in some cases.
• Previously, changing the ref to a component would always detach the ref before that component’s render is called. Now, we change the ref later, when applying the changes to the DOM.
• It is not safe to re-render into a container that was modified by something other than React. This worked previously in some cases but was never supported. We now emit a warning in this case. Instead you should clean up your component trees using ReactDOM.unmountComponentAtNode. See this example.
• componentDidUpdate lifecycle no longer receives prevContext param. (See #8631)
• Shallow renderer no longer calls componentDidUpdate because DOM refs are not available. This also makes it consistent with componentDidMount (which does not get called in previous versions either).
• Shallow renderer does not implement unstable_batchedUpdates anymore.
• ReactDOM.unstable_batchedUpdates now only takes one extra argument after the callback.

Packaging

• There is no react/lib/* and react-dom/lib/* anymore. Even in CommonJS environments, React and ReactDOM are precompiled to single files (“flat bundles”). If you previously relied on undocumented React internals, and they don’t work anymore, let us know about your specific case in a new issue, and we’ll try to figure out a migration strategy for you.
• There is no react-with-addons.js build anymore. All compatible addons are published separately on npm, and have single-file browser versions if you need them.
• The deprecations introduced in 15.x have been removed from the core package. React.createClass is now available as create-react-class, React.PropTypes as prop-types, React.DOM as react-dom-factories, react-addons-test-utils as react-dom/test-utils, and shallow renderer as react-test-renderer/shallow. See 15.5.0 and 15.6.0 blog posts for instructions on migrating code and automated codemods.

• The names and paths to the single-file browser builds have changed to emphasize the difference between development and production builds. For example:

  • react/dist/react.js → react/umd/react.development.js
  • react/dist/react.min.js → react/umd/react.production.min.js
  • react-dom/dist/react-dom.js → react-dom/umd/react-dom.development.js
  • react-dom/dist/react-dom.min.js → react-dom/umd/react-dom.production.min.js

JavaScript Environment Requirements

React 16 depends on the collection types Map and Set. If you support older browsers and devices which may not yet provide these natively (e.g. IE < 11), consider including a global polyfill in your bundled application, such as core-js or babel-polyfill.

A polyfilled environment for React 16 using core-js to support older browsers might look like:

import 'core-js/es6/map';
import 'core-js/es6/set';

import React from 'react';
import ReactDOM from 'react-dom';

ReactDOM.render(
  <h1>Hello, world!</h1>,
  document.getElementById('root')
);

React also depends on requestAnimationFrame (even in test environments).
You can use the raf package to shim requestAnimationFrame:

import 'raf/polyfill';

Acknowledgments

As always, this release would not have been possible without our open source contributors. Thanks to everyone who filed bugs, opened PRs, responded to issues, wrote documentation, and more!

Special thanks to our core contributors, especially for their heroic efforts over the past few weeks during the prerelease cycle: Brandon Dail, Jason Quense, Nathan Hunzaker, and Sasha Aickin.

Additionally, 15.6.2 adds support for the controlList attribute, and CSS columns are no longer appended with a px suffix.

Installation

We recommend using Yarn or npm for managing front-end dependencies. If you’re new to package managers, the Yarn documentation is a good place to get started.

To install React with Yarn, run:

yarn add react@^15.6.2 react-dom@^15.6.2

To install React with npm, run:

npm install --save react@^15.6.2 react-dom@^15.6.2

We recommend using a bundler like webpack or Browserify so you can write modular code and bundle it together into small packages to optimize load time.

Remember that by default, React runs extra checks and provides helpful warnings in development mode. When deploying your app, make sure to use the production build.

In case you don’t use a bundler, we also provide pre-built bundles in the npm packages which you can include as script tags on your page:

• React
  Dev build with warnings: react/dist/react.js
  Minified build for production: react/dist/react.min.js
  
• React with Add-Ons
  Dev build with warnings: react/dist/react-with-addons.js
  Minified build for production: react/dist/react-with-addons.min.js
  
• React DOM (include React in the page before React DOM)
  Dev build with warnings: react-dom/dist/react-dom.js
  Minified build for production: react-dom/dist/react-dom.min.js
  
• React DOM Server (include React in the page before React DOM Server)
  Dev build with warnings: react-dom/dist/react-dom-server.js
  Minified build for production: react-dom/dist/react-dom-server.min.js
  

We’ve also published version 15.6.2 of react and react-dom on npm, and the react package on bower.

Changelog

15.6.2 (September 25, 2017)

All Packages

• Switch from BSD + Patents to MIT license

React DOM

• Fix a bug where modifying document.documentMode would trigger IE detection in other browsers, breaking change events. (@aweary in #10032)
• CSS Columns are treated as unitless numbers. (@aweary in #10115)
• Fix bug in QtWebKit when wrapping synthetic events in proxies. (@walrusfruitcake in #10115)
• Prevent event handlers from receiving extra argument in development. (@aweary in #10115)
• Fix cases where onChange would not fire with defaultChecked on radio inputs. (@jquense in #10156)
• Add support for controlList attribute to DOM property whitelist (@nhunzaker in #9940)
• Fix a bug where creating an element with a ref in a constructor did not throw an error in development. (@iansu in #10025)

// Your code:
<div mycustomattribute="something" />

would render an empty div to the DOM with React 15:

// React 15 output:
<div />

In React 16, we are making a change. Now, any unknown attributes will end up in the DOM:

// React 16 output:
<div mycustomattribute="something" />

Why Are We Changing This?

React has always provided a JavaScript-centric API to the DOM. Since React components often take both custom and DOM-related props, it makes sense for React to use the camelCase convention just like the DOM APIs:

<div tabIndex="-1" />

This has not changed. However, the way we enforced it in the past forced us to maintain a whitelist of all valid React DOM attributes in the bundle:

// ...
summary: 'summary',
tabIndex: 'tabindex'
target: 'target',
title: 'title',
// ...

This had two downsides:

• You could not pass a custom attribute. This is useful for supplying browser-specific non-standard attributes, trying new DOM APIs, and integrating with opinionated third-party libraries.

• The attribute list kept growing over time, but most React canonical attribute names are already valid in the DOM. Removing most of the whitelist helped us reduce the bundle size a little bit.

With the new approach, both of these problems are solved. With React 16, you can now pass custom attributes to all HTML and SVG elements, and React doesn’t have to include the whole attribute whitelist in the production version.

Note that you should still use the canonical React naming for known attributes:

// Yes, please
<div tabIndex="-1" />

// Warning: Invalid DOM property `tabindex`. Did you mean `tabIndex`?
<div tabindex="-1" />

In other words, the way you use DOM components in React hasn’t changed, but now you have some new capabilities.

Should I Keep Data in Custom Attributes?

No. We don’t encourage you to keep data in DOM attributes. Even if you have to, data- attributes are probably a better approach, but in most cases data should be kept in React component state or external stores.

However, the new feature is handy if you need to use a non-standard or a new DOM attribute, or if you need to integrate with a third-party library that relies on such attributes.

Data and ARIA Attributes

Just like before, React lets you pass data- and aria- attributes freely:

<div data-foo="42" />
<button aria-label="Close" onClick={onClose} />

This has not changed.

Accessibility is very important, so even though React 16 passes any attributes through, it still validates that aria- props have correct names in development mode, just like React 15 did.

Migration Path

We have included a warning about unknown attributes since React 15.2.0 which came out more than a year ago. The vast majority of third-party libraries have already updated their code. If your app doesn’t produce warnings with React 15.2.0 or higher, this change should not require modifications in your application code.

If you still accidentally forward non-DOM props to DOM components, with React 16 you will start seeing those attributes in the DOM, for example:

<div myData='[Object object]' />

This is somewhat safe (the browser will just ignore them) but we recommend to fix these cases when you see them. One potential hazard is if you pass an object that implements a custom toString() or valueOf() method that throws. Another possible issue is that legacy HTML attributes like align and valign will now be passed to the DOM. They used to be stripped out because React didn’t support them.

To avoid these problems, we suggest to fix the warnings you see in React 15 before upgrading to React 16.

Changes in Detail

We’ve made a few other changes to make the behavior more predictable and help ensure you’re not making mistakes. We don’t anticipate that these changes are likely to break real-world applications.

These changes only affect DOM components like <div>, not your own components.

Below is a detailed list of them.

• Unknown attributes with string, number, and object values:

  <div mycustomattribute="value" />
  <div mycustomattribute={42} />
  <div mycustomattribute={myObject} />
  

  React 15: Warns and ignores them.
  React 16: Converts values to strings and passes them through.

  Note: attributes starting with on are not passed through as an exception because this could become a potential security hole.

• Known attributes with a different canonical React name:

  <div tabindex="-1" />
  <div class="hi" />
  

  React 15: Warns and ignores them.
  React 16: Warns but converts values to strings and passes them through.

  Note: always use the canonical React naming for all supported attributes.

• Non-boolean attributes with boolean values:

  <div className={false} />
  

  React 15: Converts booleans to strings and passes them through.
  React 16: Warns and ignores them.

• Non-event attributes with function values:

  <div className={function() {}} />
  

  React 15: Converts functions to strings and passes them through.
  React 16: Warns and ignores them.

• Attributes with Symbol values:

  <div className={Symbol('foo')} />
  

  React 15: Crashes.
  React 16: Warns and ignores them.

• Attributes with NaN values:

  <div tabIndex={0 / 0} />
  

  React 15: Converts NaNs to strings and passes them through.
  React 16: Converts NaNs to strings and passes them through with a warning.

While testing this release, we have also created an automatically generated table for all known attributes to track potential regressions.

Try It!

You can try the change in this CodePen.
It uses React 16 RC, and you can help us by testing the RC in your project!

Thanks

This effort was largely driven by Nathan Hunzaker who has been a prolific outside contributor to React.

You can find his work on this issue in several PRs over the course of last year: #6459, #7311, #10229, #10397, #10385, and #10470.

Major changes in a popular project can take a lot of time and research. Nathan demonstrated perseverance and commitment to getting this change through, and we are very thankful to him for this and other efforts.

We would also like to thank Brandon Dail and Jason Quense for their invaluable help maintaining React this year.

Future Work

We are not changing how custom elements work in React 16, but there are existing discussions about setting properties instead of attributes, and we might revisit this in React 17. Feel free to chime in if you’d like to help!

By the way, we just released the first beta of React 16 for you to try!

Behavior in React 15 and Earlier

In the past, JavaScript errors inside components used to corrupt React’s internal state and cause it to emit cryptic errors on next renders. These errors were always caused by an earlier error in the application code, but React did not provide a way to handle them gracefully in components, and could not recover from them.

Introducing Error Boundaries

A JavaScript error in a part of the UI shouldn’t break the whole app. To solve this problem for React users, React 16 introduces a new concept of an “error boundary”.

Error boundaries are React components that catch JavaScript errors anywhere in their child component tree, log those errors, and display a fallback UI instead of the component tree that crashed. Error boundaries catch errors during rendering, in lifecycle methods, and in constructors of the whole tree below them.

A class component becomes an error boundary if it defines a new lifecycle method called componentDidCatch(error, info):

class ErrorBoundary extends React.Component {
  constructor(props) {
    super(props);
    this.state = { hasError: false };
  }

  componentDidCatch(error, info) {
    // Display fallback UI
    this.setState({ hasError: true });
    // You can also log the error to an error reporting service
    logErrorToMyService(error, info);
  }

  render() {
    if (this.state.hasError) {
      // You can render any custom fallback UI
      return <h1>Something went wrong.</h1>;
    }
    return this.props.children;
  }
}

Then you can use it as a regular component:

<ErrorBoundary>
  <MyWidget />
</ErrorBoundary>

The componentDidCatch() method works like a JavaScript catch {} block, but for components. Only class components can be error boundaries. In practice, most of the time you’ll want to declare an error boundary component once and use it throughout your application.

Note that error boundaries only catch errors in the components below them in the tree. An error boundary can’t catch an error within itself. If an error boundary fails trying to render the error message, the error will propagate to the closest error boundary above it. This, too, is similar to how catch {} block works in JavaScript.

Live Demo

Check out this example of declaring and using an error boundary with React 16 beta.

Where to Place Error Boundaries

The granularity of error boundaries is up to you. You may wrap top-level route components to display a “Something went wrong” message to the user, just like server-side frameworks often handle crashes. You may also wrap individual widgets in an error boundary to protect them from crashing the rest of the application.

New Behavior for Uncaught Errors

This change has an important implication. As of React 16, errors that were not caught by any error boundary will result in unmounting of the whole React component tree.

We debated this decision, but in our experience it is worse to leave corrupted UI in place than to completely remove it. For example, in a product like Messenger leaving the broken UI visible could lead to somebody sending a message to the wrong person. Similarly, it is worse for a payments app to display a wrong amount than to render nothing.

This change means that as you migrate to React 16, you will likely uncover existing crashes in your application that have been unnoticed before. Adding error boundaries lets you provide better user experience when something goes wrong.

For example, Facebook Messenger wraps content of the sidebar, the info panel, the conversation log, and the message input into separate error boundaries. If some component in one of these UI areas crashes, the rest of them remain interactive.

We also encourage you to use JS error reporting services (or build your own) so that you can learn about unhandled exceptions as they happen in production, and fix them.

Component Stack Traces

React 16 prints all errors that occurred during rendering to the console in development, even if the application accidentally swallows them. In addition to the error message and the JavaScript stack, it also provides component stack traces. Now you can see where exactly in the component tree the failure has happened:

You can also see the filenames and line numbers in the component stack trace. This works by default in Create React App projects:

If you don’t use Create React App, you can add this plugin manually to your Babel configuration. Note that it’s intended only for development and must be disabled in production.

Why Not Use try / catch?

try / catch is great but it only works for imperative code:

try {
  showButton();
} catch (error) {
  // ...
}

However, React components are declarative and specify what should be rendered:

<Button />

Error boundaries preserve the declarative nature of React, and behave as you would expect. For example, even if an error occurs in a componentDidUpdate hook caused by a setState somewhere deep in the tree, it will still correctly propagate to the closest error boundary.

Naming Changes from React 15

React 15 included a very limited support for error boundaries under a different method name: unstable_handleError. This method no longer works, and you will need to change it to componentDidCatch in your code starting from the first 16 beta release.

For this change, we’ve provided a codemod to automatically migrate your code.

Improving Inputs

In React 15.6.0 the onChange event for inputs is a little bit more reliable and handles more edge cases, including the following:

• not firing when radio button is clicked but not changed (issue 1471)
• changing an input of type range with the arrow keys (issue 554)
• pasting text into a text area in IE11 (issue 7211)
• auto-fill in IE11 (issue 6614)
• clearing input with ‘x’ button or right-click ‘delete’ in IE11 (issue 6822)
• not firing when characters are present in the input on render in IE11 (issue 2185)

Thanks to Jason Quense and everyone who helped out on those issues and PRs.

Less Noisy Deprecation Warnings

We are also including a couple of new warnings for upcoming deprecations. These should not affect most users, and for more details see the changelog below.

After the last release, we got valuable community feedback that deprecation warnings were causing noise and failing tests. In React 15.6, we have downgraded deprecation warnings to use console.warn instead of console.error. Our other warnings will still use console.error because they surface urgent issues which could lead to bugs. Unlike our other warnings, deprecation warnings can be fixed over time and won’t cause problems in your app if shipped. We believe that downgrading the urgency of deprecation warnings will make your next update easier. Thanks to everyone who was involved in the discussion of this change.

Installation

We recommend using Yarn or npm for managing front-end dependencies. If you’re new to package managers, the Yarn documentation is a good place to get started.

To install React with Yarn, run:

yarn add react@^15.6.0 react-dom@^15.6.0

To install React with npm, run:

npm install --save react@^15.6.0 react-dom@^15.6.0

We recommend using a bundler like webpack or Browserify so you can write modular code and bundle it together into small packages to optimize load time.

Remember that by default, React runs extra checks and provides helpful warnings in development mode. When deploying your app, make sure to use the production build.

In case you don’t use a bundler, we also provide pre-built bundles in the npm packages which you can include as script tags on your page:

• React
  Dev build with warnings: react/dist/react.js
  Minified build for production: react/dist/react.min.js
  
• React with Add-Ons
  Dev build with warnings: react/dist/react-with-addons.js
  Minified build for production: react/dist/react-with-addons.min.js
  
• React DOM (include React in the page before React DOM)
  Dev build with warnings: react-dom/dist/react-dom.js
  Minified build for production: react-dom/dist/react-dom.min.js
  
• React DOM Server (include React in the page before React DOM Server)
  Dev build with warnings: react-dom/dist/react-dom-server.js
  Minified build for production: react-dom/dist/react-dom-server.min.js
  

We’ve also published version 15.6.0 of react and react-dom on npm, and the react package on bower.

Changelog

15.6.0 (June 13, 2017)

React

• Downgrade deprecation warnings to use console.warn instead of console.error. (@flarnie in #9753)
• Add a deprecation warning for React.createClass. Points users to create-react-class instead. (@flarnie in #9771)
• Add deprecation warnings and separate module for React.DOM factory helpers. (@nhunzaker in #8356)
• Warn for deprecation of React.createMixin helper, which was never used. (@aweary in #8853)

React DOM

• Add support for CSS variables in style attribute. (@aweary in #9302)
• Add support for CSS Grid style properties. (@ericsakmar in #9185)
• Fix bug where inputs mutated value on type conversion. (@nhunzaker in #9806)
• Fix issues with onChange not firing properly for some inputs. (@jquense in #8575)
• Fix bug where controlled number input mistakenly allowed period. (@nhunzaker in #9584)
• Fix bug where performance entries were being cleared. (@chrisui in #9451)

React Addons

• Fix AMD support for addons depending on react. (@flarnie in #9919)
• Fix isMounted() to return true in componentWillUnmount. (@mridgway in #9638)
• Fix react-addons-update to not depend on native Object.assign. (@gaearon in #9937)
• Remove broken Google Closure Compiler annotation from create-react-class. (@gaearon in #9933)
• Remove unnecessary dependency from react-linked-input. (@gaearon in #9766)
• Point react-addons-(css-)transition-group to the new package. (@gaearon in #9937)

Today, we are excited to announce that many features that have been in the pipeline for the last few months are finally released.

As usual with Create React App, you can enjoy these improvements in your existing non-ejected apps by updating a single dependency and following our migration instructions.

Newly created apps will get these improvements automatically.

webpack 2

This change was contributed by @Timer in #1291.

We have upgraded to webpack 2 which has been officially released a few months ago. It is a big upgrade with many bugfixes and general improvements. We have been testing it for a while, and now consider it stable enough to recommend it to everyone.

While the Webpack configuration format has changed, Create React App users who didn’t eject don’t need to worry about it as we have updated the configuration on our side.

If you had to eject your app for one reason or another, Webpack provides a configuration migration guide that you can follow to update your apps. Note that with each release of Create React App, we are working to support more use cases out of the box so that you don’t have to eject in the future.

The biggest notable webpack 2 feature is the ability to write and import ES6 modules directly without compiling them to CommonJS. This shouldn’t affect how you write code since you likely already use import and export statements, but it will help catch more mistakes like missing named exports at compile time:

In the future, as the ecosystem around ES6 modules matures, you can expect more improvements to your app’s bundle size thanks to tree shaking.

 Runtime Error Overlay

This change was contributed by @Timer and @nicinabox in #1101, @bvaughn in #2201.

Have you ever made a mistake in code and only realized it after the console is flooded with cryptic errors? Or worse, have you ever shipped an app with crashes in production because you accidentally missed an error in development?

To address these issues, we are introducing an overlay that pops up whenever there is an uncaught error in your application. It only appears in development, and you can dismiss it by pressing Escape.

A GIF is worth a thousand words:

(Yes, it integrates with your editor!)

In the future, we plan to teach the runtime error overlay to understand more about your React app. For example, after React 16 we plan to show React component stacks in addition to the JavaScript stacks when an error is thrown.

Progressive Web Apps by Default

This change was contributed by @jeffposnick in #1728.

Newly created projects are built as Progressive Web Apps by default. This means that they employ service workers with an offline-first caching strategy to minimize the time it takes to serve the app to the users who visit it again. You can opt out of this behavior, but we recommend it both for new and existing apps, especially if you target mobile devices.

New apps automatically have these features, but you can easily convert an existing project to a Progressive Web App by following our migration guide.

We will be adding more documentation on this topic in the coming weeks. Please feel free to ask any questions on the issue tracker!

Jest 20

This change was contributed by @rogeliog in #1614 and @gaearon in #2171.

We are now using the latest version of Jest that includes numerous bugfixes and improvements. You can read more about the changes in Jest 19 and Jest 20 blog posts.

Highlights include a new immersive watch mode, a better snapshot format, improvements to printing skipped tests, and new testing APIs.

Additionally, Create React App now support configuring a few Jest options related to coverage reporting.

Code Splitting with Dynamic import()

This change was contributed by @Timer in #1538 and @tharakawj in #1801.

It is important to keep the initial JavaScript payload of web apps down to the minimum, and load the rest of the code on demand. Although Create React App supported code splitting using require.ensure() since the first release, it used a webpack-specific syntax that did not work in Jest or other environments.

In this release, we are adding support for the dynamic import() proposal which aligns with the future web standards. Unlike require.ensure(), it doesn’t break Jest tests, and should eventually become a part of JavaScript. We encourage you to use import() to delay loading the code for non-critical component subtrees until you need to render them.

Better Console Output

This change was contributed by @gaearon in #2120, #2125, and #2161.

We have improved the console output across the board.

For example, when you start the development server, we now display the LAN address in additional to the localhost address so that you can quickly access the app from a mobile device on the same network:

When lint errors are reported, we no longer show the warnings so that you can concentrate on more critical issues. Errors and warnings in the production build output are better formatted, and the build error overlay font size now matches the browser font size more closely.

But Wait… There’s More!

You can only fit so much in a blog post, but there are other long-requested features in this release, such as environment-specific and local .env files, a lint rule against confusingly named globals, support for multiple proxies in development, a customizable browser launch script, and many bugfixes.

You can read the full changelog and the migration guide in the v1.0.0 release notes.

Acknowledgements

This release is a result of months of work from many people in the React community. It is focused on improving both developer and end user experience, as we believe they are complementary and go hand in hand.

We are grateful to everyone who has offered their contributions, whether in code, documentation, or by helping other people. We would like to specifically thank Joe Haddad for his invaluable help maintaining the project.

We are excited to bring these improvements to everybody using Create React App, and we are looking forward to more of your feedback and contributions.