{"id":11839,"library":"react-refresh","title":"React Refresh","description":"React Refresh is the core package that implements Fast Refresh, React's official hot reloading mechanism designed for a superior development experience. This feature allows developers to instantly see changes to React components without losing their local state, significantly speeding up the feedback loop during development. It achieves this by updating only the necessary component code and re-rendering, preserving state for functional components and Hooks. The `react-refresh` package itself, currently at version 0.18.0 (last published in October 2025), provides the underlying runtime and Babel transform. It is primarily consumed by bundler-specific plugins, such as `@pmmmwh/react-refresh-webpack-plugin` for Webpack or `@vitejs/plugin-react` for Vite, rather than being imported directly into application code. It maintains an active release cadence, with updates demonstrating sustainable maintenance. Fast Refresh differentiates itself from older hot-reloading solutions by being officially supported by the React team, offering greater reliability, and prioritizing safe state preservation.","status":"active","version":"0.18.0","language":"javascript","source_language":"en","source_url":"https://github.com/facebook/react","tags":["javascript","react"],"install":[{"cmd":"npm install react-refresh","lang":"bash","label":"npm"},{"cmd":"yarn add react-refresh","lang":"bash","label":"yarn"},{"cmd":"pnpm add react-refresh","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core React library for UI building, required for components to refresh. Fast Refresh is supported in React 16.10 and above, with full features in React 18+.","package":"react","optional":false},{"reason":"Provides DOM-specific rendering methods for React applications. Works alongside 'react'.","package":"react-dom","optional":false},{"reason":"Webpack plugin that integrates React Refresh for hot module replacement in Webpack-based projects. Requires 'react-refresh' as a peer dependency.","package":"@pmmmwh/react-refresh-webpack-plugin","optional":true},{"reason":"Vite plugin that provides React Fast Refresh support for Vite-based projects. Handles 'react-refresh' internally.","package":"@vitejs/plugin-react","optional":true},{"reason":"Commonly used with Webpack to transpile JavaScript/TypeScript, integrating the 'react-refresh/babel' transform.","package":"babel-loader","optional":true},{"reason":"Required for Babel transformations, including 'react-refresh/babel'.","package":"@babel/core","optional":true}],"imports":[{"note":"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.","symbol":"react-refresh/babel","correct":"plugins: ['react-refresh/babel'] // in Babel config or babel-loader options"},{"note":"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.","wrong":"import {$RefreshReg$, $RefreshSig$} from 'react-refresh/runtime'","symbol":"$RefreshReg$, $RefreshSig$","correct":"// Handled by bundler plugins, e.g., injected preamble. Not for direct app import."},{"note":"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.","wrong":"import { ReactRefreshWebpackPlugin } from 'react-refresh'","symbol":"ReactRefreshWebpackPlugin","correct":"import ReactRefreshWebpackPlugin from '@pmmmwh/react-refresh-webpack-plugin'"},{"note":"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`.","wrong":"import reactRefresh from '@vitejs/plugin-react-refresh'","symbol":"react","correct":"import react from '@vitejs/plugin-react'"}],"quickstart":{"code":"import { defineConfig } from 'vite';\nimport react from '@vitejs/plugin-react';\n\n// vite.config.ts or vite.config.js\nexport default defineConfig({\n  plugins: [\n    react({\n      // The `@vitejs/plugin-react` plugin automatically enables Fast Refresh\n      // (Hot Module Replacement) for React components by default in development mode.\n      // It leverages 'react-refresh' internally. No explicit import of 'react-refresh'\n      // or manual Fast Refresh configuration is typically needed directly in the app.\n      // 'jsxRuntime: \"automatic\"' is a common modern setting for React 17+.\n      jsxRuntime: 'automatic',\n      // 'fastRefresh: true' is the default for development mode in this plugin.\n      // You generally don't need to explicitly set it unless overriding.\n      fastRefresh: process.env.NODE_ENV !== 'production',\n    }),\n  ],\n  // Ensure the Vite development server is configured for HMR (this is the default behavior).\n  server: {\n    hmr: true,\n  },\n  // For TypeScript, if you're using it, ensure your tsconfig.json has 'jsx: \"react-jsx\"' or 'jsx: \"react-jsxdev\"'.\n  // For example, in tsconfig.json:\n  // {\n  //   \"compilerOptions\": {\n  //     \"jsx\": \"react-jsxdev\"\n  //   }\n  // }\n});","lang":"typescript","description":"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."},"warnings":[{"fix":"Migrate class components to functional components using Hooks for full Fast Refresh benefits.","message":"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.","severity":"gotcha","affected_versions":">=0.10.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=0.10.0"},{"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.","message":"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.","severity":"breaking","affected_versions":">=0.10.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=0.10.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=0.10.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","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.","error":"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."},{"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.","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.","error":"Error: Hot Module Replacement (HMR) is not enabled! React-refresh requires HMR to function properly."},{"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.","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.","error":"Warning: Invalid hook call. Hooks can only be called inside of the body of a function component."},{"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.","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.","error":"Uncaught ReferenceError: $RefreshReg$ is not defined."}],"ecosystem":"npm"}