Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Next.js and React

$RefreshSig$ or $RefreshReg$ is not defined with React Refresh in webpack

Error$RefreshSig$ is not defined

Short answer

The Babel plugin react-refresh/babel inserts calls to $RefreshSig$ and $RefreshReg$, and the webpack plugin defines them at runtime. If code is transformed by Babel but runs where the webpack plugin was not applied, such as a child compiler or a production build, the helpers are missing and the error follows.

  • Applies to webpack 5, @pmmmwh/react-refresh-webpack-plugin, react-refresh 0.10 or newer, Node.js 22
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Find out which file throws. If it is an HTML template, a web worker or another separately compiled entry, the first cause applies; if the page itself breaks only in one build mode, read the second.

    grep -n "react-refresh" webpack.config.* package.json babel.config.* .babelrc 2>/dev/null
  2. 2Match what you see, then jump to its fix

    1. 1The error comes from a worker bundle or a file processed through html-webpack-plugin or worker-plugin.The file is built by a child compiler where the plugin does not runFix
    2. 2The page breaks in a production build or in a setup where only one of the two is enabled.The Babel plugin is on but the webpack plugin is offFix

What does the error look like?

  • $RefreshSig$ is not defined
  • $RefreshReg$ is not defined

Cause 1 of 2

The file is built by a child compiler where the plugin does not run

1Check

The troubleshooting page explains that child compilers usually do not apply plugins but do apply loaders. Babel therefore adds the helper calls, and nothing defines them.

grep -rn "worker\|html-webpack-plugin" webpack.config.*

2Fix

Best fix: give those files a Babel rule without react-refresh/babel, using oneOf so the first matching rule wins. A quick fix is to define empty stand-ins at the top of the worker entry. Renaming exports away from PascalCase also makes the Babel plugin skip a file.

// worker entry: quick stand-ins
self.$RefreshReg$ = () => {};
self.$RefreshSig$ = () => () => {};

// webpack.config.js: separate rules
rules: [{
  oneOf: [
    { test: /\.[jt]s$/, include: /src\/workers/, exclude: /node_modules/,
      use: { loader: 'babel-loader' } },
    { test: /\.[jt]sx?$/, exclude: [/src\/workers/, /node_modules/],
      use: { loader: 'babel-loader',
             options: { plugins: [isDevelopment && 'react-refresh/babel'].filter(Boolean) } } },
  ],
}],

3Verify

Restart the dev server; the worker or template loads without the error in the console.

npx webpack serve

Confirmed by github.com

Did this fix it?

Cause 2 of 2

The Babel plugin is on but the webpack plugin is off

1Check

The README tells you to turn on react-refresh/babel and ReactRefreshWebpackPlugin together and only in development, with hot module replacement enabled.

grep -n "isDevelopment\|NODE_ENV\|ReactRefresh\|hot:" webpack.config.*

2Fix

Drive both from one flag, and keep devServer.hot on.

const ReactRefreshWebpackPlugin = require('@pmmmwh/react-refresh-webpack-plugin');
const isDevelopment = process.env.NODE_ENV !== 'production';

module.exports = {
  mode: isDevelopment ? 'development' : 'production',
  devServer: { hot: true },
  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),
};

3Verify

A production build runs without the helper calls, and the dev server hot-reloads components.

NODE_ENV=production npx webpack
npx webpack serve

Confirmed by github.com

Did this fix it?

How do I stop it coming back?

  • Use one isDevelopment flag for mode, the Babel plugin and the webpack plugin.
  • Keep worker and template entry files in their own folder so a Babel rule can exclude the refresh transform.
  • Reserve PascalCase names for real React components.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.