webpack-fast-refresh

React Fast Refresh for webpack@5+ and [email protected]+

IMPORTANT NOTE

This repository is to be considered EXPERIMENTAL. For most use cases we recommend using the officially endorsed webpack plugin available at pmmmwh/react-refresh-webpack-plugin.

Usage

1. Install both react-refresh and webpack-fast-refresh

npm install -D -E @webhotelier/webpack-fast-refresh react-refresh
# or
yarn add -D -E @webhotelier/webpack-fast-refresh react-refresh

2. Configure webpack

Make the following changes to your webpack.config.js:

a) Register the plugin:

const ReactRefreshPlugin = require('@webhotelier/webpack-fast-refresh');

config.plugins.unshift(new ReactRefreshPlugin());

// or if you have an object-based config:
{
  ...otherSettings,
  plugins: [new ReactRefreshPlugin(), ...otherplugins];
}

b) Place the runtime in front of your entrypoint:

Depending on how you have configured your entry, change it similarly to the following examples:

- config.entry = './index.js'; // or
- config.entry = ['./index.js'];
+ config.entry = ['@webhotelier/webpack-fast-refresh/runtime.js', './index.js'];

- config.entry = {
-   import: './index.js', // or
-   import: ['./index.js'],
- };
+ config.entry = {
+   import: ['@webhotelier/webpack-fast-refresh/runtime.js', './index.js'],
+ };

- config.main.entry = './index.js'; // or
- config.main.entry = ['./index.js'];
+ config.main.entry = [
+   '@webhotelier/webpack-fast-refresh/runtime.js',
+   './index.js',
+ ];

{
  "entry": {
-     "main": "./index.js" // or
-     "main": ["./index.js"]
+     "main": ["@webhotelier/webpack-fast-refresh/runtime.js", "./index.js"]
  }
}

c) Place the loader in your rule matching React files:

{
  "module": {
    "rules": [
      {
        "test": /\.jsx$/,
        "use": [
          { "loader": "babel-loader", "options": { "cacheDirectory": true } },
+          { "loader": "@webhotelier/webpack-fast-refresh/loader.js" }
        ]
      }
    ]
  }
}

or push it with code:

// make sure to use the index of your JSX loader, 0 in this example
config.module.rules[0].use.push('@webhotelier/webpack-fast-refresh/loader.js');

3. Configure babel

Add react-refresh/babel to your babelrc:

{
  "presets": [["@babel/preset-react", { "runtime": "automatic" }]],
+  "plugins": ["react-refresh/babel"]
}

4. Configure error-overlay plugin (optional)

const ErrorOverlayPlugin = require('@webhotelier/webpack-fast-refresh/error-overlay');
config.plugins.push(new ErrorOverlayPlugin());

// or if you have an object-based config:
{
  ...otherSettings,
  plugins: [new ErrorOverlayPlugin(), ...otherplugins];
}

5. Launch the server

Make sure you have HMR enabled.

Using webpack-dev-server:

webpack-dev-server --hot --mode development

Using webpack-hot-middleware:

In webpack.config.js:

config.entry.main.unshift(require.resolve('webpack-hot-middleware/client'));
config.plugins.push(new webpack.HotModuleReplacementPlugin());

In your node server:

if (app.get('env') === 'development') {
  const webpack = require('webpack');
  const webpackConfig = require('./webpack.config.json');
  const webpackCompiler = webpack(webpackConfig);

  app.use(
    require('webpack-dev-middleware')(webpackCompiler, {
      lazy: false,
      publicPath: webpackConfig.output.publicPath,
      headers: { 'Access-Control-Allow-Origin': '*' },
    })
  );

  app.use(
    require('webpack-hot-middleware')(webpackCompiler, {
      path: '/__webpack_hmr',
      heartbeat: 10 * 1000,
      noInfo: false,
      quiet: false,
    })
  );
}

Common Issues

html-webpack-plugin

This plugin is not compatible with html-webpack-plugin at the moment.

Production problems

The above plugin & loader DO NOT check if they are running in production builds and do not automatically disable themselves. Make sure you add the correct checks to only include them in development builds.

References

• @next/react-refresh-utils
• @pmmmwh/react-refresh-webpack-plugin
• Implementation by @maisano