Fast Refresh & HMR Explained

The plain-language idea

When you save a file in a React dev server, the whole page usually doesn't reload. Fast Refresh (React's implementation of Hot Module Replacement for components) swaps in the new component code in place, and — when it can — keeps the existing component instances mounted, with their state intact. Toggle a modal open, edit a line of JSX in that modal's component, save: the modal is still open. That's Fast Refresh working.

It works by re-running the module and comparing the new component function to the old one. If it still looks like "the same component" (same file, same export, compatible enough), React swaps the render function but reuses the existing fiber and its state. If the edit changes something React can't safely reconcile that way, it falls back to unmounting and remounting the component fresh — state gone, same as a page reload for that subtree.

See it in a real thing: what survives, what doesn't

function Counter() {
  const [count, setCount] = useState(0);
  return (
    <button onClick={() => setCount((c) => c + 1)}>
      {/* editing this label and saving: count survives */}
      Clicked {count} times
    </button>
  );
}

Editing that label, a class name, or the JSX structure below the hooks and saving — the button re-renders with the new markup, count keeps whatever value it had. Now compare:

function Counter() {
  const [count, setCount] = useState(0);
  const [label, setLabel] = useState("times"); // added this line and saved
  return (
    <button onClick={() => setCount((c) => c + 1)}>
      Clicked {count} {label}
    </button>
  );
}

Adding a second useState call changes the order and shape of hooks for every already-mounted instance of Counter. React can't safely map "the old fiber's hook slot 0" onto a component that now expects two hook slots without risking corrupted state, so Fast Refresh remounts the component instead — count resets to 0.

What people usually miss

Watch out

• Class components never preserve state across Fast Refresh, ever. The state-preserving swap only works for function components — editing a class component always triggers a full remount of that subtree, which is one more reason most teams have moved on from class components for anything actively edited.
• A file that exports anything other than components loses Fast Refresh entirely for that module. If a component file also exports a constant, a plain utility function, or a non-component value, the bundler can't be sure the module is "component-only," so it falls back to a full reload of everything that imports it. This is why linters like react-refresh/only-export-components flag mixed exports.
• Editing a custom hook's file cascades a full reload to every component that uses it, not a targeted state-preserving swap — Fast Refresh's identity tracking is keyed to the component doing the rendering, not to hooks in isolation.
• A syntax error doesn't break Fast Refresh permanently. The dev server shows an overlay, keeps the last working version mounted underneath it, and resumes normal Fast Refresh the moment the file parses again — you don't lose your app state just because of a typo mid-edit.

The genealogy: this is reconciliation's identity rule, applied to editing

The same rule that makes React reuse a fiber across renders — same component type in the same position — is what Fast Refresh leans on across edits, not just re-renders. And the reason adding a hook resets state is the same reason the rules of hooks forbid conditional hook calls in the first place: React tracks hook state by call order, not by name, so any change to that order or count is treated as a fundamentally different component.