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:
facebook/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.

[gaearon]

By the way I edited my guide to include a missing piece I forgot — the performReactRefresh call. That’s the thing that actually schedules updates.

[theKashey]

isLikelyComponentType(type) {
   return typeof type === 'function' && /^[A-Z]/.test(type.name);
},

I would not feel safe with such logic. Even if all CapitalizedFunctions are React components almost always - many modules (of mine) has other exports as well. For example exports-for-tests. That's not a problem, but creates some unpredictability - hot boundary could be created at any point... or not created after one line change.
What could break isLikelyComponentType test:

• exported mapStateToProps (for tests, not used in a production code)
• exported hook (and that's ok)
• exported Class which might be not a react class (would not, but should)

So - there would be cases when hot boundary shall be established, but would not, and there would be a cases when hot boundary would be established, but shall not. Sounds like old good unstable hot-reloading we both don't quite like :)

There is one place where applying hot boundary would be not so unpredictable, and would be quite expected - a thing or domain boundary, or a directory index, ie an index.js reexporting a "public API" from the Component.js in the same directory (not a Facebook style afaik).

In other words - everything like you did in Metro, but with more limitations applied. Everything else, like linting rule to have such boundary established for any lazy loaded component, could be used to enforce the correct behaviour.

Speaking of which - hot fast refresh would handle Lazy? Is it expected to have boundary from the other side of the import?

[pekala]

Gave it a quick try to see the magic in the browser and it is so nice :) I did the simplest possible thing, i.e. hardcoding all the instrumentation code, so no webpack plugins there yet

Repo here: https://github.com/pekala/react-refresh-test

[natew]

Just curious but for webpack, couldn't you just have a babel plugin to wrap the try/finally? Just want to be sure I'm not missing something before giving it a shot.

[gaearon]

The Babel plugin is not environment specific. I’d like to keep it that way. It doesn’t know anything about modules or update propagation mechanism. Those differ depending on the bundler.

For example in Metro there’s no try/finally wrapping transform at all. Instead I put try/finally in the bundler runtime itself around where it calls the module factory. That would be ideal with webpack too but I don’t know if it lets you hook into the runtime like that.

You could of course create another Babel plugin for wrapping. But that doesn’t buy you anything over doing that via webpack. Since it’s webpack-specific anyway. And it can be confusing that you could accidentally run that Babel plugin in another environment (not webpack) where it wouldn’t make sense.

[Jessidhia]

You can, by hooking into the compilation.mainTemplate.hooks.require waterfall hook. The previous invocation of it is the default body of the __webpack_require__ function, so you can tap into the hook to wrap the contents into a try/finally block.

The problem is getting a reference to React inside the __webpack_require__. It's possible, but might require some degree of reentrancy and recursion guards.

For more details, check MainTemplate.js and web/JsonpMainTemplatePlugin.js in the webpack source code. JsonpMainTemplatePlugin itself just taps into a bunch of hooks from MainTemplate.js so that's probably the "meat" that you need to tackle.

[maisano]

Here's a harebrained prototype I hacked together that does effectively what Dan outlined above. It's woefully incomplete, but proves out a lo-fi implementation in webpack: https://gist.github.com/maisano/441a4bc6b2954205803d68deac04a716

Some notes:

• react-dom is hardcoded here, so this would not work with custom renderers or sub-packages (e.g. react-dom/profiling).
• I haven't looked too deeply into how all of webpack's template variants work, but the way I wrapped module execution is quite hacky. I'm not certain if this example would work if, say, one uses the umd library target.

[gaearon]

The problem is getting a reference to React inside the webpack_require. It's possible, but might require some degree of reentrancy and recursion guards.

I assume you mean getting a reference to Refresh Runtime.

In Metro I’ve solved this by doing require.Refresh = RefreshRuntime as early as possible. Then inside the require implementation I can read a property off the require function itself. It won’t be available immediately but it won’t matter if we set it early enough.

[natew]

@maisano I had to change a number of things, and ultimately I'm not seeing the .accept function called by webpack. I've tried both .accept(module.i, () => {}) and .accept(() => {}) (self-accepting, except this doesn't work in webpack). The hot property is enabled, I see it come down and run through accepted modules.

So I ended up patching webpack to call self-accepting modules, and that was the final fix.

Here's the patch:

diff --git a/node_modules/webpack/lib/HotModuleReplacement.runtime.js b/node_modules/webpack/lib/HotModuleReplacement.runtime.js
index 5756623..7e0c681 100644
--- a/node_modules/webpack/lib/HotModuleReplacement.runtime.js
+++ b/node_modules/webpack/lib/HotModuleReplacement.runtime.js
@@ -301,7 +301,10 @@ module.exports = function() {
 				var moduleId = queueItem.id;
 				var chain = queueItem.chain;
 				module = installedModules[moduleId];
-				if (!module || module.hot._selfAccepted) continue;
+				if (!module || module.hot._selfAccepted) {
+					module && module.hot._selfAccepted()
+					continue;
+				}
 				if (module.hot._selfDeclined) {
 					return {
 						type: "self-declined",

I know this goes against their API, which wants that to be an "errorCallback", I remember running into this specifically many years ago working on our internal HMR, and ultimately we ended up writing our own bundler. I believe parcel supports the "self-accepting" callback API. Perhaps it's worth us opening an issue on webpack and seeing if we can get it merged? @sokra

[pmmmwh]

So ... I further polished the plugin based on the work of @maisano :
https://github.com/pmmmwh/react-refresh-webpack-plugin
(I wrote it in TypeScript because I don't trust myself fiddling with webpack internals when I started, I can convert that to plain JS/Flow)

I tried to remove the need of a loader for injecting the hot-module code with webpack Dependency classes, but seemingly that will require a re-parse of all modules (because even with all functions inline, we still need a reference to react-refresh/runtime in somewhere).

Another issue is that there are no simple ways (afaik) to detect JavaScript-like files in webpack - for example html-webpack-plugin uses the javascript/auto type as well, so I hard-coded what seems to be an acceptable file mask (JS/TS/Flow) for loader injection.

I also added error recovery (at least syntax error) based on comment from @gaearon in this 5-year old thread. Next is recovering from react errors - I suspect this can be done by injecting a global error boundary (kinda like AppWrapper of react-hot-loader), which will also tackle the error-box interface, but did not have the time to get to that just quite yet.

The issue raised by @natew is also avoided - achieved by decoupling the enqueueUpdate call and the hot.accpet(errorHandler) call.

[maisano]

@pmmmwh What timing! I just created a repo which built on/tweaked a little of the work I had shared in the gist.

I haven't gotten to error-handling in any case, though the plugin here is a bit more solid than the initial approach I had taken.

[giles-v]

@gaearon I'm trying to implement Fast Refresh into our website, a large application using RequireJS as a module loader. Without something like webpack's hot-reload API, I'm struggling to work out a mechanism to substitute in.

Using a custom TS transformer (we're not using Babel currently) I'm wrapping each define call in an IIFE which creates a local $RefreshReg$ and $RefreshSig$, and at the end of the define function body, I'm calling runtime.register with the exports local variable. (Incidentally, I'm not clear how these two $ functions are used, I couldn't see invocations of them anywhere).

For each module modified locally, we have a custom function to create a new RequireJS context, load in the modified module file (including the above transforms) and patch it in by copying exports from the newly loaded module to the original module. After doing that, I'm then calling performReactRefresh.

And the above works, for the specific module changed. But the refresh does not bubble up, so if I've just changed a file exporting a string, the component which imports that string won't see any changes applied. If we were using Webpack, we would look to see if the newly loaded component was a boundary, and hot.invalidate if not, bubbling to the parent and calling performReactRefresh once we hit a boundary.

Figuring out the parent module(s) to bubble to is complex; it would require me to maintain an inverted tree of the whole application in parallel outside RequireJS. But even if I do that, I don't have a way to specifically instruct fast-refresh to mark the parent as needing an update. I could hot-reload the parent so that the module source is re-executed, but that destroys state.

As a "sledgehammer to crack a nut" solution, is there a way to simply mark the whole tree as pending update before calling the performReactRefresh function?

[gaearon]

(Incidentally, I'm not clear how these two $ functions are used, I couldn't see invocations of them anywhere).

The calls are generated by the react-refresh/babel Babel plugin. Do you have it applied? Without it, nothing else will work.

[gaearon]

I could hot-reload the parent so that the module source is re-executed, but that destroys state.

Why does it destroy the state? I don't think it should if the parent component is registered.

[theKashey]

@gaearon , @pmmmwh - it's probably a good time officially say goodby to our dear friend React-Hot-Loader.
Can you please help me fill some holes to provide a direction for the users still using it in order to migrate to FastRefresh with less friction? 👉 gaearon/react-hot-loader#1848

RHL still has 1M weekly downloads, which is hopefully 1/7th of react-refresh-webpack-plugin, but that is quite a lot in any case.

[geoHeil]

Sadly, I am not an JS expert. Trying to migrate away from react-hot-loader.

import { AppContainer } from "react-hot-loader";
ReactDOM.render(
    <AppContainer>

What is the suggested upgrade path when moving over to babel with react-refresh (or whatever else is currently the supported solution) https://github.com/pmmmwh/react-refresh-webpack-plugin ?

[theKashey]

You dont need to change you runtime to support fast refresh. Just completely remove RHL and then install https://github.com/pmmmwh/react-refresh-webpack-plugin following it's pretty simple and short instructions - update babel config and add webpack plugin.