$RefreshSig$ or $RefreshReg$ is not defined with React Refresh in webpack
$RefreshSig$ is not definedShort 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.
Fix it fast
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/null2Match what you see, then jump to its fix
- 1
The 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
The 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
- 1
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 serveConfirmed by github.com
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 serveConfirmed by github.com
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:
- TaxiDexMy own multi-tenant taxi dispatch SaaS: API, dispatcher portal, driver and passenger apps, and the servers underneath.
- QistLockA NestJS and React SaaS driving an Android Device Owner agent that locks financed phones when payments lapse.
- WorkforceA field app, an admin console and a self-hosted Node.js server for push and reconciliation.
Related fixes
Web apps
React shows Attempted import error when importing a component or function
Attempted import error:
The build found the file but not the name you asked for.
2 causes, each with a fixWeb apps
AxiosError Network Error with code ERR_NETWORK in a React app
Network Error
ERR_NETWORK means the request produced no readable response.
4 causes, each with a fixWeb apps
Axios get works with a URL string but ignores the object passed as the second argument
The server log shows a GET with no query string
axios.get takes a URL and an optional config object.
3 causes, each with a fixWeb apps
Can't resolve '../axios' in a React project
Module not found: Error: Can't resolve '../axios'
A path that starts with ./ or ../ is a file path, not the axios package.
3 causes, each with a fixWeb apps
Axios returns 401 from a React app but the login works elsewhere
Error: Request failed with status code 401
A 401 means the server received the request without valid credentials.
3 causes, each with a fixWeb apps
An axios call never finishes when the API server stops answering
code: 'ECONNABORTED'
Axios has no timeout unless you give it one: the default is 0, which means wait forever.
3 causes, each with a fix