Convert Figma logo to code with AI

pmmmwh logoreact-refresh-webpack-plugin

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

3,128
192
3,128
61

Top Related Projects

Set up a modern web app by running one command.

124,777

The React Framework

67,112

Next generation frontend tooling. It's fast!

Serves a webpack app. Updates the browser on changes. Documentation https://webpack.js.org/configuration/dev-server/.

Tweak React components in real time. (Deprecated: use Fast Refresh instead.)

Create and build modern JavaScript projects with zero initial configuration.

Quick Overview

The react-refresh-webpack-plugin is a Webpack plugin that enables fast, reliable, and consistent live-reloading for React applications. It provides a seamless development experience by automatically updating the browser when changes are made to the codebase, without the need for a full page refresh.

Pros

  • Fast and Reliable: The plugin leverages React's built-in Fast Refresh feature, ensuring that updates are applied quickly and without interrupting the user's workflow.
  • Consistent Behavior: The plugin maintains a consistent behavior across different browsers and environments, providing a reliable development experience.
  • Easy Integration: The plugin is designed to be easily integrated into existing Webpack-based React projects, with minimal configuration required.
  • Compatibility: The plugin supports a wide range of React versions, from 16.9 to the latest, ensuring compatibility with your project's requirements.

Cons

  • Webpack-specific: The plugin is designed specifically for Webpack, which may limit its usefulness for developers using other bundlers like Rollup or Parcel.
  • Potential Compatibility Issues: While the plugin supports a wide range of React versions, there may be edge cases or specific project configurations where compatibility issues could arise.
  • Limited Customization: The plugin provides a relatively limited set of configuration options, which may not meet the needs of all developers.
  • Dependency on React Fast Refresh: The plugin's performance and reliability are dependent on the stability and performance of the React Fast Refresh feature, which is still an experimental technology.

Code Examples

Here are a few examples of how to use the react-refresh-webpack-plugin in your Webpack configuration:

  1. Basic Configuration:
const ReactRefreshWebpackPlugin = require('@pmmmwh/react-refresh-webpack-plugin');

module.exports = {
  // ... other Webpack configuration
  plugins: [
    new ReactRefreshWebpackPlugin(),
  ],
  devServer: {
    hot: true,
  },
};
  1. Customizing the Plugin:
const ReactRefreshWebpackPlugin = require('@pmmmwh/react-refresh-webpack-plugin');

module.exports = {
  // ... other Webpack configuration
  plugins: [
    new ReactRefreshWebpackPlugin({
      overlay: {
        sockPort: 8080, // Custom socket port
      },
    }),
  ],
  devServer: {
    hot: true,
    port: 8080, // Custom dev server port
  },
};
  1. Integrating with Babel:
module.exports = {
  // ... other Webpack configuration
  module: {
    rules: [
      {
        test: /\.(js|jsx)$/,
        exclude: /node_modules/,
        use: [
          {
            loader: 'babel-loader',
            options: {
              plugins: [
                require.resolve('react-refresh/babel'),
              ],
            },
          },
        ],
      },
    ],
  },
  plugins: [
    new ReactRefreshWebpackPlugin(),
  ],
  devServer: {
    hot: true,
  },
};
  1. Disabling the Plugin in Production:
const ReactRefreshWebpackPlugin = require('@pmmmwh/react-refresh-webpack-plugin');

module.exports = (env) => {
  const isProduction = env.production;

  return {
    // ... other Webpack configuration
    plugins: [
      !isProduction && new ReactRefreshWebpackPlugin(),
    ].filter(Boolean),
    devServer: {
      hot: !isProduction,
    },
  };
};

Getting Started

To get started with the react-refresh-webpack-plugin, follow these steps:

  1. Install the plugin and its dependencies:
npm install --save-dev @pmmmwh/react-refresh-webpack-plugin react-refresh
  1. Update your Webpack configuration to include the plugin:
const ReactRefreshWebpackPlugin = require('@pmmmwh/react-refresh-webpack-plugin');

module.exports = {
  // ... other Webpack configuration
  plugins: [
    new ReactRefreshWeb

Competitor Comparisons

Set up a modern web app by running one command.

Pros of Create React App

  • Provides a complete, opinionated setup for React projects out of the box
  • Includes a development server, build tools, and testing utilities
  • Abstracts away complex configuration, making it easier for beginners

Cons of Create React App

  • Less flexibility in configuration compared to custom Webpack setups
  • Can be overkill for smaller projects or those requiring specific optimizations
  • Updating to newer versions can sometimes be challenging due to dependencies

Code Comparison

Create React App:

import React from 'react';
import ReactDOM from 'react-dom';
import App from './App';

ReactDOM.render(<App />, document.getElementById('root'));

React Refresh Webpack Plugin:

const ReactRefreshWebpackPlugin = require('@pmmmwh/react-refresh-webpack-plugin');

module.exports = {
  // ... other webpack config
  plugins: [
    new ReactRefreshWebpackPlugin(),
  ],
};

While Create React App provides a complete React development environment, React Refresh Webpack Plugin focuses specifically on enabling fast refresh functionality in custom Webpack setups. Create React App is ideal for quickly starting new React projects, whereas React Refresh Webpack Plugin offers more granular control over the development experience in existing Webpack configurations.

124,777

The React Framework

Pros of Next.js

  • Full-featured React framework with built-in routing, server-side rendering, and API routes
  • Automatic code splitting and optimized performance out of the box
  • Extensive ecosystem and community support

Cons of Next.js

  • Steeper learning curve for developers new to server-side rendering concepts
  • Less flexibility in customizing the build process compared to a standalone Webpack plugin

Code Comparison

Next.js (pages/index.js):

export default function Home() {
  return <h1>Welcome to Next.js!</h1>
}

react-refresh-webpack-plugin (webpack.config.js):

const ReactRefreshWebpackPlugin = require('@pmmmwh/react-refresh-webpack-plugin');

module.exports = {
  // ... other webpack configurations
  plugins: [new ReactRefreshWebpackPlugin()],
};

Summary

Next.js is a comprehensive React framework that provides a full-stack solution, while react-refresh-webpack-plugin is a focused tool for enabling Fast Refresh in Webpack-based React applications. Next.js offers more features and abstractions but may be overkill for simpler projects. The Webpack plugin provides more granular control over the development experience but requires manual setup and integration with other tools.

67,112

Next generation frontend tooling. It's fast!

Pros of Vite

  • Faster development server startup and hot module replacement
  • Built-in support for TypeScript, JSX, and CSS modules without additional configuration
  • Optimized build process with pre-bundling of dependencies

Cons of Vite

  • Less mature ecosystem compared to Webpack-based solutions
  • May require adjustments for projects heavily reliant on Webpack-specific features
  • Limited plugin ecosystem compared to Webpack

Code Comparison

react-refresh-webpack-plugin configuration:

const ReactRefreshWebpackPlugin = require('@pmmmwh/react-refresh-webpack-plugin');

module.exports = {
  // ... other webpack config
  plugins: [new ReactRefreshWebpackPlugin()],
};

Vite configuration:

// vite.config.js
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'

export default defineConfig({
  plugins: [react()]
})

Summary

Vite offers a more streamlined development experience with faster startup times and built-in support for modern web technologies. However, react-refresh-webpack-plugin may be more suitable for projects deeply integrated with Webpack or requiring specific Webpack features. Vite's configuration is generally simpler, but it may require additional adjustments for complex projects transitioning from Webpack.

Serves a webpack app. Updates the browser on changes. Documentation https://webpack.js.org/configuration/dev-server/.

Pros of webpack-dev-server

  • More comprehensive development server solution with built-in hot module replacement (HMR)
  • Broader compatibility with various webpack configurations and project types
  • Extensive documentation and large community support

Cons of webpack-dev-server

  • Heavier setup and configuration required for optimal performance
  • May not provide as seamless React component state preservation during hot reloading

Code Comparison

webpack-dev-server configuration:

module.exports = {
  devServer: {
    contentBase: './dist',
    hot: true
  }
};

react-refresh-webpack-plugin configuration:

const ReactRefreshWebpackPlugin = require('@pmmmwh/react-refresh-webpack-plugin');

module.exports = {
  plugins: [
    new ReactRefreshWebpackPlugin()
  ]
};

Summary

webpack-dev-server is a more versatile development server solution with broader application, while react-refresh-webpack-plugin focuses specifically on enhancing React development experience with improved hot reloading capabilities. The choice between the two depends on project requirements and the level of React-specific optimization needed.

Tweak React components in real time. (Deprecated: use Fast Refresh instead.)

Pros of react-hot-loader

  • More mature and battle-tested, with a longer history of use in production environments
  • Supports a wider range of React versions, including older ones
  • Offers more configuration options for advanced use cases

Cons of react-hot-loader

  • Higher performance overhead, especially for larger applications
  • More complex setup and configuration process
  • Occasional issues with state preservation during hot reloading

Code Comparison

react-hot-loader:

import { hot } from 'react-hot-loader/root';
import App from './App';

export default hot(App);

react-refresh-webpack-plugin:

// No additional code required in your React components
// Configuration is done in webpack.config.js

react-refresh-webpack-plugin generally requires less boilerplate code in your React components, as most of the configuration is done in the webpack config file. This leads to cleaner component code and easier maintenance.

react-hot-loader, while more verbose, offers greater flexibility in terms of which components are hot-reloadable and how they behave during updates.

Overall, react-refresh-webpack-plugin is becoming the preferred choice for newer projects due to its improved performance, simpler setup, and better integration with modern React features. However, react-hot-loader still has its place, especially in projects with specific requirements or those using older React versions.

Create and build modern JavaScript projects with zero initial configuration.

Pros of Neutrino

  • More comprehensive build tool that provides a complete development environment
  • Offers a modular approach with presets for various frameworks and tools
  • Supports multiple programming paradigms and project types

Cons of Neutrino

  • Steeper learning curve due to its broader scope and functionality
  • May introduce unnecessary complexity for simpler projects
  • Less focused on specific React hot reloading functionality

Code Comparison

Neutrino configuration:

module.exports = {
  use: [
    '@neutrinojs/react',
    '@neutrinojs/jest',
    neutrino => {
      neutrino.config.module.rule('compile').use('babel').options({
        plugins: [require.resolve('react-refresh/babel')]
      });
    }
  ]
};

React Refresh Webpack Plugin configuration:

const ReactRefreshWebpackPlugin = require('@pmmmwh/react-refresh-webpack-plugin');

module.exports = {
  plugins: [new ReactRefreshWebpackPlugin()]
};

While Neutrino provides a more comprehensive build setup, React Refresh Webpack Plugin focuses specifically on enabling fast refresh functionality for React applications. Neutrino requires more configuration but offers greater flexibility, whereas React Refresh Webpack Plugin is simpler to set up for its specific use case.

Convert Figma logo designs to code with AI

Visual Copilot

Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.

Try Visual Copilot

README

React Refresh Webpack Plugin

CircleCI License Latest Version Next Version

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

This plugin is not 100% stable. 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:

DependencyVersion
react16.13.0+, 17.x or 18.x
react-dom16.13.0+, 17.x or 18.x
react-refresh0.10.0+
webpack4.46.0+ or 5.2.0+
Minimum requirements
DependencyVersion
react16.9.0
react-dom16.9.0
react-refresh0.10.0
webpack4.43.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 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.

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 npm
npm install -D type-fest

# if you prefer yarn
yarn add -D type-fest

# if you prefer pnpm
pnpm 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).

const isDevelopment = process.env.NODE_ENV !== 'production';

module.exports = {
  mode: isDevelopment ? 'development' : 'production',
  devServer: {
    hot: true,
  },
};
Using webpack-hot-middleware
const webpack = require('webpack');

const isDevelopment = process.env.NODE_ENV !== 'production';

module.exports = {
  mode: isDevelopment ? 'development' : 'production',
  plugins: [isDevelopment && new webpack.HotModuleReplacementPlugin()].filter(Boolean),
};
Using webpack-plugin-serve
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!

Using ts-loader

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

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

# 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

Then, instead of wiring up react-refresh/babel via babel-loader, you can wire-up react-refresh-typescript with ts-loader:

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),
};

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.

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:

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),
};

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.

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:

DependencyVersion
webpack-dev-server3.6.0+ or 4.x or 5.x
webpack-hot-middleware2.x
webpack-plugin-serve0.x or 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

JetBrains Logo

NPM DownloadsLast 30 Days