React Refresh

Common errors

• Module not found: Error: You attempted to import /.../node_modules/react-refresh/runtime.js which falls outside of the project src/ directory. Relative imports outside of src/ are not supported.

  cause This typically occurs when `react-refresh/runtime.js` is being directly imported or referenced in application code, or when the build setup (e.g., Webpack or Vite configuration) is incorrectly trying to bundle it as part of the application source.
  fix Ensure `react-refresh/runtime.js` is not directly imported in your application code. This module is intended to be injected and managed by bundler plugins during development. Verify your bundler configuration is set up correctly for Fast Refresh, and that `react-refresh` is configured as a `devDependencies` (or `peerDependencies`) and handled by build tools. If using Create React App, ensure it's up to date and that `FAST_REFRESH=false` is not unintentionally set.

• Error: Hot Module Replacement (HMR) is not enabled! React-refresh requires HMR to function properly.

  cause Fast Refresh fundamentally relies on a Hot Module Replacement (HMR) mechanism provided by the underlying bundler (Webpack, Vite, etc.). This error indicates that HMR is not correctly configured or enabled in the development server setup.
  fix Verify that HMR is explicitly enabled in your bundler's development server configuration (e.g., `devServer.hot: true` in Webpack or Vite's default HMR settings). Ensure the necessary HMR plugins or settings are active in development mode.

• Warning: Invalid hook call. Hooks can only be called inside of the body of a function component.

  cause While not exclusively a `react-refresh` error, this warning can sometimes appear when there are multiple or conflicting versions of React in the `node_modules` tree, which can be exacerbated by issues with Fast Refresh setup or dependency resolution in complex projects or monorepos.
  fix Inspect your dependency tree using `npm ls react` or `yarn why react` to identify duplicate or conflicting React versions. Use `npm dedupe` or `yarn resolutions` in `package.json` to force a single, consistent React version across your project. Ensure you are using the latest compatible versions of React, React DOM, and all related Fast Refresh plugins.

• Uncaught ReferenceError: $RefreshReg$ is not defined.

  cause This error occurs when the `react-refresh/babel` transform processes code, expecting the global `$RefreshReg$` and `$RefreshSig$` functions to be available, but they have not been injected by the bundler's runtime. This is common in indirect code paths like Web Workers or JS templates where the standard Fast Refresh runtime injection doesn't happen.
  fix For code paths that require Babel transformation with `react-refresh/babel` but are not part of the main application bundle (and thus miss the runtime injection), manually 'polyfill' these globals at the entry point of that specific code path (e.g., `self.$RefreshReg$ = () => {}; self.$RefreshSig$ = () => () => {};`). Additionally, ensure any components or variables in such indirect paths that don't render React are not named in PascalCase, to prevent the Babel plugin from processing them unnecessarily.

Warnings

• gotcha Fast Refresh does not preserve local state for React class components; it only works reliably with functional components and Hooks. Class components will typically remount on changes, losing their state.
  Fix: Migrate class components to functional components using Hooks for full Fast Refresh benefits.
• gotcha Files that export both React components and non-React values (e.g., constants, utility functions) may cause Fast Refresh to fall back to a full page reload or re-run more modules than necessary. Similarly, un-named/anonymous or non-PascalCased React components can prevent Fast Refresh from working optimally.
  Fix: Separate non-React exports into their own files. Ensure all React components are named (not anonymous) and follow PascalCase naming conventions. Consider using `eslint-plugin-react-refresh` to enforce these rules.
• breaking React Refresh and its associated bundler plugins (like `@pmmmwh/react-refresh-webpack-plugin` or `@vitejs/plugin-react`) are designed exclusively for development environments. Enabling them in production builds can introduce vulnerabilities, unnecessary code, and performance overhead.
  Fix: Always ensure `react-refresh/babel` and any Fast Refresh bundler plugins are conditionally applied only when `process.env.NODE_ENV === 'development'` or similar development environment flags are active.
• gotcha Version mismatches between `react-refresh` and its bundler-specific integration plugins (e.g., `@pmmmwh/react-refresh-webpack-plugin`) can lead to Fast Refresh failures, broken HMR, or unexpected behavior.
  Fix: Regularly update all related packages (react, react-dom, react-refresh, and its bundler plugins) to their latest compatible versions. Use `npm ls react-refresh` or `yarn why react-refresh` to inspect the dependency tree for conflicting versions and consider `npm dedupe` or `package.json` 'overrides' if conflicts persist.
• gotcha Using the `// @refresh reset` comment anywhere in a file will force components defined in that file to be completely remounted on every edit, resetting their state, even if Fast Refresh would normally preserve it. This is an intentional override but can lead to unexpected state loss if used inadvertently.
  Fix: Use `// @refresh reset` only when a full remount and state reset is explicitly desired, for example, when debugging mount animations or specific lifecycle effects. Be mindful of its impact on developer experience.

Install

• npm install react-refresh npm
• yarn add react-refresh yarn
• pnpm add react-refresh pnpm

Imports

• react-refresh/babel

  plugins: ['react-refresh/babel'] // in Babel config or babel-loader options

  This is a Babel plugin, not a direct JavaScript import. It transforms React components for Fast Refresh compatibility, enabling the runtime. Ensure it's only enabled in development mode.
• $RefreshReg$, $RefreshSig$
  wrong:

  import {$RefreshReg$, $RefreshSig$} from 'react-refresh/runtime'

  correct:

  // Handled by bundler plugins, e.g., injected preamble. Not for direct app import.

  These global functions are part of the `react-refresh/runtime` API, which are injected into the global scope by bundler plugins during development. Direct manual import from `react-refresh/runtime` is generally incorrect and can lead to 'module not found' errors or broken refresh functionality. For indirect code paths (like Web Workers) that require Babel transform but aren't processed by bundler plugins, manual 'polyfills' like `self.$RefreshReg$ = () => {}; self.$RefreshSig$ = () => () => {};` may be necessary.
• ReactRefreshWebpackPlugin
  wrong:

  import { ReactRefreshWebpackPlugin } from 'react-refresh'

  correct:

  import ReactRefreshWebpackPlugin from '@pmmmwh/react-refresh-webpack-plugin'

  This plugin is part of `@pmmmwh/react-refresh-webpack-plugin`, which is a separate package that consumes `react-refresh` as a peer dependency. Do not try to import it directly from the `react-refresh` package.
• react
  wrong:

  import reactRefresh from '@vitejs/plugin-react-refresh'

  correct:

  import react from '@vitejs/plugin-react'

  For Vite, the primary plugin `@vitejs/plugin-react` (or the older `@vitejs/plugin-react-refresh`) handles Fast Refresh integration. It is imported from its own package, not directly from `react-refresh`.

Quickstart

This Vite configuration demonstrates how to set up Fast Refresh for a React project using the official `@vitejs/plugin-react`. This plugin transparently integrates `react-refresh` to provide hot module reloading during development.

import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';

// vite.config.ts or vite.config.js
export default defineConfig({
  plugins: [
    react({
      // The `@vitejs/plugin-react` plugin automatically enables Fast Refresh
      // (Hot Module Replacement) for React components by default in development mode.
      // It leverages 'react-refresh' internally. No explicit import of 'react-refresh'
      // or manual Fast Refresh configuration is typically needed directly in the app.
      // 'jsxRuntime: "automatic"' is a common modern setting for React 17+.
      jsxRuntime: 'automatic',
      // 'fastRefresh: true' is the default for development mode in this plugin.
      // You generally don't need to explicitly set it unless overriding.
      fastRefresh: process.env.NODE_ENV !== 'production',
    }),
  ],
  // Ensure the Vite development server is configured for HMR (this is the default behavior).
  server: {
    hmr: true,
  },
  // For TypeScript, if you're using it, ensure your tsconfig.json has 'jsx: "react-jsx"' or 'jsx: "react-jsxdev"'.
  // For example, in tsconfig.json:
  // {
  //   "compilerOptions": {
  //     "jsx": "react-jsxdev"
  //   }
  // }
});