Repository files navigation

AnEXPERIMENTAL Webpack plugin to enable "Fast Refresh" (also previously known asHot Reloading) for React components.

First and foremost, this plugin is not 100% stable.We're working towards a stable v1 release, and we've been testing the plugin quite extensively;but since it is still pretty young, there might still be some unknown edge cases.

There are no breaking changes planned for the v1 release,but they might still happen if we hit some significant road blockers.

Also, ensure that you are using the minimum supported versions of the plugin's peer dependencies -older versions unfortunately do not contain code to orchestrate "Fast Refresh",and thus cannot be made compatible.

You only needreact-dom if you're rendering to the DOM.

You only need to check forreact-reconciler if you use custom reconcilers likereact-three-fiber.You should check theirpackage.json to make sure they use a compatible version instead of installingreact-reconciler yourself.If the reconcilers are not compatible, please create an issue at their repository.

With all prerequisites met, you can install the plugin with one of the commands below:

# 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 plugin depends on a package from the React team -react-refresh,so you will have to install and configure it separately as demonstrated in theUsage section.

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

For that you will have to installtype-fest as a development peer dependency with one of the commands below:

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

The most basic setup to enable "Fast Refresh" is to update yourwebpack.config.js (or.ts) as follows:

constReactRefreshWebpackPlugin=require('@pmmmwh/react-refresh-webpack-plugin');constwebpack=require('webpack');// ... your other importsconstisDevelopment=process.env.NODE_ENV!=='production';module.exports={// It is suggested to run both `react-refresh/babel` and the plugin in the `development` mode only,// even though both of them have optimisations in place to do nothing in the `production` mode.// If you would like to override Webpack's defaults for modes, you can also use the `none` mode -// you then will need to set `forceEnable: true` in the plugin's options.mode:isDevelopment ?'development' :'production',module:{rules:[// ... other rules{test:/\.[jt]sx?$/,exclude:/node_modules/,use:[// ... other loaders{loader:require.resolve('babel-loader'),options:{// ... other optionsplugins:[// ... other pluginsisDevelopment&&require.resolve('react-refresh/babel'),].filter(Boolean),},},],},],},plugins:[// ... other pluginsisDevelopment&&newwebpack.HotModuleReplacementPlugin(),isDevelopment&&newReactRefreshWebpackPlugin(),].filter(Boolean),// ... other configuration options};

You might want to further tweak the configuration to accommodate your setup:

• isDevelopment

  In this example we've shown the simple way of splitting updevelopment andproduction builds with theNODE_ENV environment variable.It will default totrue (i.e.development mode) whenNODE_ENV is not available from the environment.

  In practice though, you might want to wire this up differently,likeusing a function config or using multiple configuration files.

• webpack.HotModuleReplacementPlugin

  If you usewebpack-dev-server orwebpack-plugin-serve,you can setdevServer.hot/devServer.hotOnly andhmr totrue respectively,instead of adding the HMR plugin to your plugin list.

Note: If you are using TypeScript (instead of Babel) as a transpiler, you will still need to usebabel-loader to process your source code.Check out thissample project on how to set this up.

Officially,webpack-dev-server,webpack-hot-middleware andwebpack-plugin-serve are supported out of the box -you just have to set theoverlay.sockIntegration option to match what you're using.

For each of the integrations listed above,you can also take a look at the correspondingsample projects for a better understanding of how things should be wired up.

Please refer tothe API docs for all available options.

Please refer tothe Troubleshooting guide for FAQs and resolutions to common issues.

This project is licensed under the terms of theMIT License.

• Initial Implementation by @maisano