A Webpack plugin to enable "Fast Refresh" (also known as Hot Reloading) for React components.
We're hoping to land a v1 release soon - please help us by reporting any issues you've encountered!
Getting Started
Prerequisites
Ensure that you are using at least the minimum supported versions of this plugin's peer dependencies -
older versions unfortunately do not contain code to orchestrate "Fast Refresh",
and thus cannot be made compatible.
We recommend using the following versions:
Dependency
Version
Node.js
18.12.0+, 20.x, 22.x
react
16.13.0+, 17.x, 18.x or 19.x
react-dom
16.13.0+, 17.x, 18.x or 19.x
react-refresh
0.10.0+
webpack
5.2.0+
Minimum requirements
Dependency
Version
Node.js
18.12.0
react
16.9.0
react-dom
16.9.0
react-refresh
0.10.0
webpack
5.2.0
Using custom renderers (e.g. react-three-fiber, react-pdf, ink)
To ensure full support of "Fast Refresh" with components rendered by custom renderers,
you should ensure the renderer you're using depends on a recent version of react-reconciler.
We recommend version 0.25.0 or above, but any versions above 0.22.0 should work.
If the renderer is not compatible, please file them an issue instead.
Installation
With all prerequisites met, you can install this plugin using your package manager of choice:
# if you prefer npmnpm install -D @pmmmwh/react-refresh-webpack-plugin react-refresh# if you prefer yarnyarn add -D @pmmmwh/react-refresh-webpack-plugin react-refresh# if you prefer pnpmpnpm add -D @pmmmwh/react-refresh-webpack-plugin react-refresh
The react-refresh package (from the React team) is a required peer dependency of this plugin.
We recommend using version 0.10.0 or above.
Support for TypeScript
TypeScript support is available out-of-the-box for those who use webpack.config.ts.
Our exported types however depends on type-fest, so you'll have to add it as a devDependency:
# if you prefer npmnpm install -D type-fest# if you prefer yarnyarn add -D type-fest# if you prefer pnpmpnpm add -D type-fest
:memo: Note:
type-fest@4.x only supports Node.js v16 or above,
type-fest@3.x only supports Node.js v14.16 or above,
and type-fest@2.x only supports Node.js v12.20 or above.
If you're using an older version of Node.js, please install type-fest@1.x.
Usage
For most setups, we recommend integrating with babel-loader.
It covers the most use cases and is officially supported by the React team.
The example below will assume you're using webpack-dev-server.
If you haven't done so, set up your development Webpack configuration for Hot Module Replacement (HMR).
# if you prefer npmnpm install -D react-refresh-typescript# if you prefer yarnyarn add -D react-refresh-typescript# if you prefer pnpmpnpm add -D react-refresh-typescript
Then, instead of wiring up react-refresh/babel via babel-loader,
you can wire-up react-refresh-typescript with ts-loader:
const ReactRefreshWebpackPlugin = require
Using swc-loader
:warning: Warning:
This is an un-official integration maintained by the community.
Ensure your @swc/core version is at least 1.2.86.
It is also recommended to use swc-loader version 0.1.13 or above.
Then, instead of wiring up react-refresh/babel via babel-loader,
you can wire-up swc-loader and use the refresh transform:
plugins: [isDevelopment && new ReactRefreshWebpackPlugin()].filter(Boolean),
};
It is recommended to run ts-loader with transpileOnly is set to true.
You can use ForkTsCheckerWebpackPlugin as an alternative if you need typechecking during development.
use: [
{
loader: require.resolve('swc-loader'),
options: {
jsc: {
transform: {
react: {
development: isDevelopment,
refresh: isDevelopment,
},
},
},
},
},
],
},
],
},
plugins: [isDevelopment && new ReactRefreshWebpackPlugin()].filter(Boolean),
};
Starting from version 0.1.13, swc-loader will set the development option based on Webpack's mode option.
swc won't enable fast refresh when development is false.