Have ideas to improve npm?Join in the discussion! »

    TypeScript icon, indicating that this package has built-in type declarations

    0.4.3 • Public • Published

    React Refresh Webpack Plugin

    Latest Version Next Version CircleCI License

    An EXPERIMENTAL Webpack plugin to enable "Fast Refresh" (also previously known as Hot 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.

    Dependency Minimum Best
    react 16.9.0 16.13.0+
    react-dom 16.9.0 16.13.0+
    react-reconciler 0.22.0 0.25.0+
    webpack 4.0.0 (for 0.3.x)
    4.43.0 (for 0.4.x+)

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

    You only need to check for react-reconciler if you use custom reconcilers like react-three-fiber. You should check their package.json to make sure they use a compatible version instead of installing react-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 npm 
    npm install -D @pmmmwh/react-refresh-webpack-plugin react-refresh
    # if you prefer yarn 
    yarn add -D @pmmmwh/react-refresh-webpack-plugin react-refresh
    # if you prefer pnpm 
    pnpm 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 the Usage section, too.


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

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

    # if you prefer npm 
    npm install -D type-fest
    # if you prefer yarn 
    yarn add -D type-fest
    # if you prefer pnpm 
    pnpm add -D type-fest


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

    const ReactRefreshWebpackPlugin = require('@pmmmwh/react-refresh-webpack-plugin');
    const webpack = require('webpack');
    // ... your other imports
    const isDevelopment = 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 options
                  plugins: [
                    // ... other plugins
                    isDevelopment && require.resolve('react-refresh/babel'),
      plugins: [
        // ... other plugins
        isDevelopment && new webpack.HotModuleReplacementPlugin(),
        isDevelopment && new ReactRefreshWebpackPlugin(),
      // ... 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 up development and production builds with the NODE_ENV environment variable. It will default to true (i.e. development mode) when NODE_ENV is not available from the environment.

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

    • webpack.HotModuleReplacementPlugin

      If you use webpack-dev-server or webpack-plugin-serve, you can set devServer.hot/devServer.hotOnly and hmr to true 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 use babel-loader to process your source code. Check out this sample project on how to set this up.

    Integration Support for Overlay

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

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


    Please refer to the API docs for all available options.

    FAQs and Troubleshooting

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


    This project is licensed under the terms of the MIT License.

    Related Work


    npm i @pmmmwh/react-refresh-webpack-plugin

    DownloadsWeekly Downloads






    Unpacked Size

    105 kB

    Total Files


    Last publish


    • avatar