React Refresh Webpack Plugin

[actions]: https://github.com/pmmmwh/react-refresh-webpack-plugin/actions/workflows/ci.yml [actions:badge]: https://img.shields.io/github/actions/workflow/status/pmmmwh/react-refresh-webpack-plugin/ci.yml?branch=main [license:badge]: https://img.shields.io/github/license/pmmmwh/react-refresh-webpack-plugin [npm:latest]: https://www.npmjs.com/package/@pmmmwh/react-refresh-webpack-plugin/v/latest [npm:latest:badge]: https://img.shields.io/npm/v/@pmmmwh/react-refresh-webpack-plugin/latest [npm:next]: https://www.npmjs.com/package/@pmmmwh/react-refresh-webpack-plugin/v/next [npm:next:badge]: https://img.shields.io/npm/v/@pmmmwh/react-refresh-webpack-plugin/next

[![GitHub Actions][actions:badge]][actions] [![License][license:badge]](./LICENSE) [![Latest Version][npm:latest:badge]][npm:latest] [![Next Version][npm:next:badge]][npm:next]

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+ |

Installation

With all prerequisites met, you can install this plugin using your package manager of choice:

# 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 react-refresh package (from the React team) is a required peer dependency of this plugin. We recommend using version 0.10.0 or above.

# 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

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).

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

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

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

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

const ReactRefreshWebpackPlugin = require('@pmmmwh/react-refresh-webpack-plugin');
const isDevelopment = 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 && new ReactRefreshWebpackPlugin()].filter(Boolean),
};

:memo: Note:

> Ensure both the Babel transform (react-refresh/babel) and this plugin are enabled only in development mode!

# if you prefer npm
npm install -D react-refresh-typescript
if you prefer yarn
yarn add -D react-refresh-typescript
if you prefer pnpm
pnpm add -D react-refresh-typescript

const ReactRefreshWebpackPlugin = require('@pmmmwh/react-refresh-webpack-plugin');
const ReactRefreshTypeScript = require('react-refresh-typescript');
const isDevelopment = 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 && new ReactRefreshWebpackPlugin()].filter(Boolean),
};

const ReactRefreshWebpackPlugin = require('@pmmmwh/react-refresh-webpack-plugin');
const isDevelopment = 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 && new ReactRefreshWebpackPlugin()].filter(Boolean),
};

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

Overlay Integration

This plugin integrates with the most common Webpack HMR solutions to surface errors during development - in the form of an error overlay.

By default, webpack-dev-server is used, but you can set the overlay.sockIntegration option to match what you're using.

The supported versions are as follows:

| Dependency | Version | | ------------------------ | -------------------------- | | webpack-dev-server | 4.8.0+ or 5.x or 6.x | | webpack-hot-middleware | 2.x | | webpack-plugin-serve | 1.x |

API

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.

License

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

Special Thanks