How should we set up apps for HMR now that Fast Refresh replaces react-hot-loader?

[shirakaba]

Dan Abramov mentioned that Devtools v4 will be making react-hot-loader obsolete: https://twitter.com/dan_abramov/status/1144715740983046144?s=20

Me:
I have this hook:
require("react-reconciler")(hostConfig).injectIntoDevTools(opts);
But HMR has always worked completely without it. Is this now a new requirement?

Dan:
Yes, that's what the new mechanism uses. The new mechanism doesn't need "react-hot-loader" so by the time you update, you'd want to remove that package. (It's pretty invasive)

I can't see any mention of HMR in the Devtools documentation, however; now that react-hot-loader has become obsolete (and with it, the require("react-hot-loader/root").hot method), how should we set up apps for HMR in:

• React DOM apps
• React Native apps
• React custom renderer apps

I'd be particularly interested in a migration guide specifically for anyone who's already set up HMR via react-hot-loader.

Also, for HMR, does it matter whether we're using the standalone Devtools or the browser-extension Devtools?

[bvaughn]

There's some confusion. The new DevTools doesn't enable hot reloading (or have anything to do with reloading). Rather, the hot reloading changes Dan has been working on makes use of the "hook" that DevTools and React use to communicate. It adds itself into the middle so it can do reloading.

I've edited the title to remove mention of DevTools (since it may cause confusion).

[bvaughn]

As for the question about how the new HMR should be used, I don't think I know the latest thinking there. I see @gaearon has a wip PR over on the CRA repo:
react/create-react-app#5958

[gaearon]

As for the question about how the new HMR should be used, I don't think I know the latest thinking there. I see @gaearon has a wip PR over on the CRA repo:

To clarify for readers, that PR is very outdated and not relevant anymore.

---

I need to write something down about how Fast Refresh works and how to integrate it. Haven't had time yet.

[gaearon]

Okay, here goes.

What Is Fast Refresh?

It's a reimplementation of "hot reloading" with full support from React. It's originally shipping for React Native but most of the implementation is platform-independent. The plan is to use it across the board — as a replacement for purely userland solutions (like react-hot-loader).

Can I Use Fast Refresh on the Web?

Theoretically, yes, that's the plan. Practically, someone needs to integrate it with bundlers common on the web (e.g. Webpack, Parcel). I haven't gotten around to doing that yet. Maybe someone wants to pick it up. This comment is a rough guide for how you’d do it.

What Does It Consist Of?

Fast Refresh relies on several pieces working together:

• "Hot module replacement" mechanism in the module system.
  • That is usually also provided by the bundler.
  • E.g. in webpack, module.hot API lets you do this.
• React renderer 16.9.0+ (e.g. React DOM 16.9)
  • Or react-reconciler@0.21.0 or higher for custom renderers
• react-refresh/runtime entry point
• react-refresh/babel Babel plugin

You'll probably want to work on the integration part. I.e. integrating react-refresh/runtime with Webpack "hot module replacement" mechanism.

What's Integration Looking Like?

⚠️⚠️⚠️ TO BE CLEAR, THIS IS A GUIDE FOR PEOPLE WHO WANT TO IMPLEMENT THE INTEGRATION THEMSELVES. THIS IS NOT A GUIDE FOR BEGINNERS OR PEOPLE WHO WANT TO START USING FAST REFRESH IN THEIR APPS. PROCEED AT YOUR OWN CAUTION! ⚠️⚠️⚠️

There are a few things you want to do minimally:

• Enable HMR in your bundler (e.g. webpack)
• Ensure React is 16.9.0+
• Add react-refresh/babel to your Babel plugins

At that point your app should crash. It should contain calls to $RefreshReg$ and $RefreshSig$ functions which are undefined.

Then you need to create a new JS entry point which must run before any code in your app, including react-dom (!) This is important; if it runs after react-dom, nothing will work. That entry point should do something like this:

if (process.env.NODE_ENV !== 'production' && typeof window !== 'undefined') {
  const runtime = require('react-refresh/runtime');
  runtime.injectIntoGlobalHook(window);
  window.$RefreshReg$ = () => {};
  window.$RefreshSig$ = () => type => type;
}

This should fix the crashes. But it still won't do anything because these $RefreshReg$ and $RefreshSig$ implementations are noops. Hooking them up is the meat of the integration work you need to do.

How you do that depends on your bundler. I suppose with webpack you could write a loader that adds some code before and after every module executes. Or maybe there's some hook to inject something into the module template. Regardless, what you want to achieve is that every module looks like this:

// BEFORE EVERY MODULE EXECUTES

var prevRefreshReg = window.$RefreshReg$;
var prevRefreshSig = window.$RefreshSig$;
var RefreshRuntime = require('react-refresh/runtime');

window.$RefreshReg$ = (type, id) => {
  // Note module.id is webpack-specific, this may vary in other bundlers
  const fullId = module.id + ' ' + id;
  RefreshRuntime.register(type, fullId);
}
window.$RefreshSig$ = RefreshRuntime.createSignatureFunctionForTransform;

try {

  // !!!
  // ...ACTUAL MODULE SOURCE CODE...
  // !!!

} finally {
  window.$RefreshReg$ = prevRefreshReg;
  window.$RefreshSig$ = prevRefreshSig;
}

The idea here is that our Babel plugin emits calls to this functions, and then our integration above ties those calls to the module ID. So that the runtime receives strings like "path/to/Button.js Button" when a component is being registered. (Or, in webpack's case, IDs would be numbers.) Don't forget that both Babel transform and this wrapping must only occur in development mode.

As alternative to wrapping the module code, maybe there's some way to add a try/finally like this around the place where the bundler actually initializes the module factory. Like we do here in Metro (RN bundler). This would probably be better because we wouldn't need to bloat up every module, or worry about introducing illegal syntax, e.g. when wrapping import with in try / finally.

Once you hook this up, you have one last problem. Your bundler doesn't know that you're handling the updates, so it probably reloads the page anyway. You need to tell it not to. This is again bundler-specific, but the approach I suggest is to check whether all of the exports are React components, and in that case, "accept" the update. In webpack it could look like something:

// ...ALL MODULE CODE...

const myExports = module.exports; 
// Note: I think with ES6 exports you might also have to look at .__proto__, at least in webpack

if (isReactRefreshBoundary(myExports)) {
  module.hot.accept(); // Depends on your bundler
  enqueueUpdate();
}

What is isReactRefreshBoundary? It's a thing that enumerates over exports shallowly and determines whether it only exports React components. That's how you decide whether to accept an update or not. I didn't copy paste it here but this implementation could be a good start. (In that code, Refresh refers to react-refresh/runtime export).

You'll also want to manually register all exports because Babel transform will only call $RefreshReg$ for functions. If you don't do this, updates to classes won't be detected.

Finally, the enqueueUpdate() function would be something shared between modules that debounces and performs the actual React update.

const runtime = require('react-refresh/runtime');

let enqueueUpdate = debounce(runtime.performReactRefresh, 30);

By this point you should have something working.

Nuances

There are some baseline experience expectations that I care about that go into "Fast Refresh" branding. It should be able to gracefully recover from a syntax error, a module initialization error, or a rendering error. I won't go into these mechanisms in detail, but I feel very strongly that you shouldn't call your experiment "Fast Refresh" until it handle those cases well.

Unfortunately, I don't know if webpack can support all of those, but we can ask for help if you get to a somewhat working state but then get stuck. For example, I've noticed that webpack's accept() API makes error recovery more difficult (you need to accept a previous version of the module after an error), but there's a way to hack around that. Another thing we'll need to get back to is to automatically "register" all exports, and not just the ones found by the Babel plugin. For now, let's ignore this, but if you have something that works for e.g. webpack, I can look at polishing it.

Similarly, we'd need to integrate it with an "error box" experience, similar to react-error-overlay we have in Create React App. That has some nuance, like the error box should disappear when you fix an error. That also takes some further work we can do once the foundation's in place.

Let me know if you have any questions!

[Jessidhia]

Syntax errors / initialization errors should be "easy enough" to handle in some way before telling React to start a render, but how would rendering errors interact with error boundaries?

If a rendering error happens, it'll trigger the closest error boundary which will snapshot itself into an error state, and there is no generic way to tell error boundaries that their children are magically possibly fixed after a live refresh. Does / should every refreshable component get its own error boundary for free, or does error handling work differently in the reconciler when the runtime support is detected on initialization?

[theKashey]

all of the exports are React components, and in that case, "accept" the update

Is there any way to detect such components? As far as I understand - no. Except export.toString().indexOf('React')>0, but it would stop working with any HOC applied.
Plus self accepting at the end of the file is not error-prone - the new accept handle would not be established, and next update would bubble to the higher boundary, that's why require("react-hot-loader/root").hot was created.

In any case - it seems to be that if one would throw all react-specific code from react-hot-loader, keeping the external API untouched - that would be enough, and applicable to all existing installations.

[natew]

Using react-refresh/babel 0.4.0 is giving me this error on a large number of files:

ERROR in ../orbit-app/src/hooks/useStores.ts
Module build failed (from ../node_modules/babel-loader/lib/index.js):
TypeError: Cannot read property '0' of undefined
    at Function.get (/Users/nw/projects/motion/orbit/node_modules/@babel/traverse/lib/path/index.js:115:33)
    at NodePath.unshiftContainer (/Users/nw/projects/motion/orbit/node_modules/@babel/traverse/lib/path/modification.js:191:31)
    at PluginPass.exit (/Users/nw/projects/motion/orbit/node_modules/react-refresh/cjs/react-refresh-babel.development.js:546:28)

I narrowed down that file to the simplest thing that causes it:

import { useContext } from 'react'

export default () => useContext()

[gaearon]

If a rendering error happens, it'll trigger the closest error boundary which will snapshot itself into an error state, and there is no generic way to tell error boundaries that their children are magically possibly fixed after a live refresh.

Fast Refresh code inside React remembers which boundaries are currently failed. Whenever a Fast Refresh update is scheduled, it will always remount them.

If there are no boundaries, but a root failed on update, Fast Refresh will retry rendering that root with its last element.

If the root failed on mount, runtime.hasUnrecoverableErrors() will tell you that. Then you have to force a reload. We could handle that case later, I didn’t have time to fix it yet.

[gaearon]

Using react-refresh/babel 0.4.0 is giving me this error on a large number of files:

File a new issue pls?

[gaearon]

Is there any way to detect such components?

I linked to my implementation, which itself uses Runtime.isLikelyAReactComponent(). It’s not perfect but it’s good enough.

the new accept handle would not be established, and next update would bubble to the higher boundary

Can you make an example? I’m not following. Regardless, that’s something specific to the bundler. I made Metro do what I wanted. We can ask webpack to add something if we’re missing an API.

The goal here is to re-execute as few modules as possible while guaranteeing consistency. We don’t want to bubble updates to the root for most edits.

it seems to be that if one would throw all react-specific code from react-hot-loader, keeping the external API untouched

Maybe, although I’d like to remove the top level container as well. I also want a tighter integration with the error box. Maybe that can still be called react-hot-loader.