Guide · Open source

How to use react-hot-loader: setup, steps and limits

Updated 2026-10-29 · written with AI from the project's own documentation and checked against our catalogue data

React Hot Loader is an MIT-licensed JavaScript library that updates React components in a running app as you edit them, keeping the current page state instead of reloading the whole page. This guide walks through the setup described in the project README, including the Babel plugin, the root component export and the webpack entry patch. The README also says the library is expected to be replaced by React Fast Refresh, so you will also learn how to check whether you should use it at all.

React Hot Loadergaearon/react-hot-loader · ★ 12.1k · MIT Install options & downloads

Quick start

1Check for Fast Refresh. Confirm that your framework or bundler does not already support React Fast Refresh. If it does, use that instead, as the README asks.
2Install the package. Run npm install react-hot-loader in your project.
3Add the Babel plugin. Add react-hot-loader/babel to the plugins list in your .babelrc file.
4Export the root component with hot. Import hot from react-hot-loader/root and wrap your root component with it as the default export.
5Load the patch before React. Import react-hot-loader before React or add react-hot-loader/patch to the start of your webpack entry.
6Start the dev server with HMR. Run webpack-dev-server --hot and edit a component to check that it updates without a full page reload.

Should you use React Hot Loader or Fast Refresh?

The README states that React Hot Loader is expected to be replaced by React Fast Refresh and asks users to remove React Hot Loader if Fast Refresh is supported in their environment.

According to the README, React Native, Parcel 2, create-react-app (from version 4 with the FAST_REFRESH environment variable) and Next.js (from version 9.4) support Fast Refresh. For webpack, Fast Refresh needs a plugin. Other bundlers have no Fast Refresh support yet, and the README says to use React Hot Loader there.

Check your framework or bundler first. If it supports Fast Refresh, prefer that.
Keep React Hot Loader only if you already use it and your setup does not yet support Fast Refresh.
Do not start a new project on React Hot Loader when Fast Refresh is available.

Install react-hot-loader with npm

Install the package as a regular dependency. The README notes that it is safe to do so because it automatically makes sure it is not executed in production and its footprint is minimal.

You need Node.js, npm or yarn, and a React project that uses a bundler such as webpack.

npm install react-hot-loader

Add the Babel plugin to your Babel config

React Hot Loader requires your code to pass through Babel so it can be hot-reloaded. Add the react-hot-loader/babel plugin to your .babelrc file.

{"plugins": ["react-hot-loader/babel"]}

Mark your root component as hot-exported

Wrap your root component with the hot function imported from react-hot-loader/root and export the result. Components inside it will update on edit.

Import hot from 'react-hot-loader/root'.
Wrap the root component with hot() and use it as the default export.

import { hot } from 'react-hot-loader/root';
const App = () => <div>Hello World!</div>;
export default hot(App);

Load react-hot-loader before React

The README says react-hot-loader must be required before react and react-dom. You can do this in one of two ways: import it at the top of your main file, or prepend the webpack entry point with the patch.

Import 'react-hot-loader' in your main file, placed before React.
Or add 'react-hot-loader/patch' as the first entry in your webpack entry array.

module.exports = {
  entry: ['react-hot-loader/patch', './src'],
};

Run webpack with Hot Module Replacement

Start your dev server with Hot Module Replacement enabled. The README gives webpack-dev-server with the --hot flag as the command.

webpack-dev-server --hot

How hooks behave with react-hot-loader

According to the README, hooks are updated on hot module replacement when they should be, as long as the dependency list is non-empty. A useState call is never updated, so its state is preserved. A useEffect with an empty dependency list acts as an on-mount hook and is not updated.

Hooks are also reloaded when a function body changes, which is on by default and controlled by the reloadHooksOnBodyChange option. The README says that hooks can be reset if their order changes, which remounts the local tree, and that the Babel plugin is required for this. Without it, changing hook order throws an error that propagates to the nearest class-based component.

Use a non-empty dependency list such as useEffect(effect, ['hot']) to make a hook reloadable.
To turn off hook reloading, call setConfig with reloadHooks set to false.

import { setConfig } from 'react-hot-loader';

setConfig({
  reloadHooks: false,
});

Know the limits before you rely on it

React Hot Loader is designed not to change the past. It only updates the present, so lifecycle methods such as componentDidMount and componentWillUnmount are not called on update, and changes to them are ignored for components that already exist. It also does not update objects, including component state.

The README says that changes to a component's constructor may not always apply, because the library knows what class functions are but not how they were created.

Changes to componentDidMount or componentWillUnmount are ignored for already created components.
Component state is not updated by hot reloading.
Some constructor changes may not apply unless the component is recreated.

Use react-hot-loader in production builds or not

The README says the webpack patch, the hot function, the Babel plugin and @hot-loader/react-dom are safe to use in production, but it also says the library is not needed there and that removing it is recommended once Fast Refresh is available. Set production mode both as an environment variable and in your bundler, and watch your bundle size.

NODE_ENV=production webpack --mode production

What people use it for

Keep form input and UI state while you tweak a component's markup or styling during development.
Maintain an existing React project that already uses React Hot Loader and has no Fast Refresh support yet.
Work on a team that uses an older bundler setup where Fast Refresh is not available.

Frequently asked questions

Is react-hot-loader deprecated?

The README says React Hot Loader is expected to be replaced by React Fast Refresh and asks users to remove it where Fast Refresh is supported. Projects on bundlers without Fast Refresh support can still use it according to the README.

Is react-hot-loader free to use?

The project is licensed under the MIT License, as shown in the README. The analysis for this listing does not cover pricing for other tools.

How do I install react-hot-loader?

Run npm install react-hot-loader. The README says it can be installed as a regular dependency, because it is not executed in production.

Does react-hot-loader work with TypeScript?

The README says React Hot Loader requires code to pass through Babel, which can be a pain point for TypeScript users who do not normally use Babel. It also says Babel can parse TypeScript syntax, so a Babel step can be added to a TypeScript build.

What is the alternative to react-hot-loader?

The README points to React Fast Refresh, which is built into React Native, Parcel 2, create-react-app and Next.js, and is available for webpack through a plugin. The analysis also lists react-refresh-webpack-plugin as a comparable project.

Why do my hooks reset or throw an error after I change them?

According to the README, changing the order of hooks resets the local tree and needs the Babel plugin. Without the plugin, the change throws an error that goes up to the nearest class-based component.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Use React Hot Loader if you already run it in an existing React project on a bundler that does not yet support Fast Refresh. For new projects, or any setup where Fast Refresh is available, pick Fast Refresh instead, since the README asks users to remove React Hot Loader in that case.

Install options & downloads