pmmmwh/react-refresh-webpack-pluginPublic

NotificationsYou must be signed in to change notification settings
Fork197
Star3.2k

A Webpack plugin to enable "Fast Refresh" (also previously known as Hot Reloading) for React components.

License

MIT license

3.2k stars 197 forks Branches Tags Activity

Star

Notifications

You must be signed in to change notification settings

Branches Tags

Folders and files

Name		Name	Last commit message	Last commit date
Latest commit History 894 Commits
.github/workflows		.github/workflows
client		client
docs		docs
examples		examples
lib		lib
loader		loader
options		options
overlay		overlay
scripts		scripts
sockets		sockets
test		test
types		types
.babelrc.json		.babelrc.json
.eslintignore		.eslintignore
.eslintrc.json		.eslintrc.json
.gitattributes		.gitattributes
.gitignore		.gitignore
.prettierignore		.prettierignore
.prettierrc.json		.prettierrc.json
CHANGELOG.md		CHANGELOG.md
LICENSE		LICENSE
README.md		README.md
jest.config.js		jest.config.js
package.json		package.json
tsconfig.json		tsconfig.json
webpack.config.js		webpack.config.js
yarn.lock		yarn.lock

Repository files navigation

React Refresh Webpack Plugin

A Webpack plugin to enable "Fast Refresh" (also known asHot 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 ofreact-reconciler.

We recommend version0.25.0 or above, but any versions above0.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

Thereact-refresh package (from the React team) is a required peer dependency of this plugin.We recommend using version0.10.0 or above.

Support for TypeScript

TypeScript support is available out-of-the-box for those who usewebpack.config.ts.

Our exported types however depends ontype-fest, so you'll have to add it as adevDependency:

# if you prefer npmnpm install -D type-fest# if you prefer yarnyarn add -D type-fest# if you prefer pnpmpnpm add -D type-fest

📝 Note:
type-fest@4.x only supports Node.js v16 or above,type-fest@3.x only supports Node.js v14.16 or above,andtype-fest@2.x only supports Node.js v12.20 or above.If you're using an older version of Node.js, please installtype-fest@1.x.

Usage

For most setups, we recommend integrating withbabel-loader.It covers the most use cases and is officially supported by the React team.

The example below will assume you're usingwebpack-dev-server.

If you haven't done so, set up your development Webpack configuration for Hot Module Replacement (HMR).

constisDevelopment=process.env.NODE_ENV!=='production';module.exports={mode:isDevelopment ?'development' :'production',devServer:{hot:true,},};

Usingwebpack-hot-middleware

constwebpack=require('webpack');constisDevelopment=process.env.NODE_ENV!=='production';module.exports={mode:isDevelopment ?'development' :'production',plugins:[isDevelopment&&newwebpack.HotModuleReplacementPlugin()].filter(Boolean),};

Usingwebpack-plugin-serve

const{ WebpackPluginServe}=require('webpack-plugin-serve');constisDevelopment=process.env.NODE_ENV!=='production';module.exports={mode:isDevelopment ?'development' :'production',plugins:[isDevelopment&&newWebpackPluginServe()].filter(Boolean),};

Then, add thereact-refresh/babel plugin to your Babel configuration and this plugin to your Webpack configuration.

constReactRefreshWebpackPlugin=require('@pmmmwh/react-refresh-webpack-plugin');constisDevelopment=process.env.NODE_ENV!=='production';module.exports={mode:isDevelopment ?'development' :'production',module:{rules:[{test:/\.[jt]sx?$/,exclude:/node_modules/,use:[{loader:require.resolve('babel-loader'),options:{plugins:[isDevelopment&&require.resolve('react-refresh/babel')].filter(Boolean),},},],},],},plugins:[isDevelopment&&newReactRefreshWebpackPlugin()].filter(Boolean),};

📝 Note:
Ensure both the Babel transform (react-refresh/babel) and this plugin are enabled only indevelopment mode!

Usingts-loader

⚠️ Warning:This is an un-official integration maintained by the community.

Installreact-refresh-typescript.Ensure your TypeScript version is at least 4.0.

# 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 upreact-refresh/babel viababel-loader,you can wire-upreact-refresh-typescript withts-loader:

constReactRefreshWebpackPlugin=require('@pmmmwh/react-refresh-webpack-plugin');constReactRefreshTypeScript=require('react-refresh-typescript');constisDevelopment=process.env.NODE_ENV!=='production';module.exports={mode:isDevelopment ?'development' :'production',module:{rules:[{test:/\.[jt]sx?$/,exclude:/node_modules/,use:[{loader:require.resolve('ts-loader'),options:{getCustomTransformers:()=>({before:[isDevelopment&&ReactRefreshTypeScript()].filter(Boolean),}),transpileOnly:isDevelopment,},},],},],},plugins:[isDevelopment&&newReactRefreshWebpackPlugin()].filter(Boolean),};

It is recommended to runts-loader withtranspileOnly is set totrue.You can useForkTsCheckerWebpackPlugin as an alternative if you need typechecking during development.

Usingswc-loader

⚠️ Warning:This is an un-official integration maintained by the community.

Ensure your@swc/core version is at least1.2.86.It is also recommended to useswc-loader version0.1.13 or above.

Then, instead of wiring upreact-refresh/babel viababel-loader,you can wire-upswc-loader and use therefresh transform:

constReactRefreshWebpackPlugin=require('@pmmmwh/react-refresh-webpack-plugin');constisDevelopment=process.env.NODE_ENV!=='production';module.exports={mode:isDevelopment ?'development' :'production',module:{rules:[{test:/\.[jt]sx?$/,exclude:/node_modules/,use:[{loader:require.resolve('swc-loader'),options:{jsc:{transform:{react:{development:isDevelopment,refresh:isDevelopment,},},},},},],},],},plugins:[isDevelopment&&newReactRefreshWebpackPlugin()].filter(Boolean),};

Starting from version0.1.13,swc-loader will set thedevelopment option based on Webpack'smode option.swc won't enable fast refresh whendevelopment isfalse.

For more information on how to set up "Fast Refresh" with different integrations,please check outour examples.