[Suggestion]: More concrete advice for writing Fast Refresh-compatible code

[bhallstein]

Summary

I'm seeking advice on writing code that is compatible with React Fast Refresh and drawing a bit of a blank. I found: https://reactnative.dev/docs/fast-refresh (NB reactnative.dev not react.dev) which has some tips but the information is not very formal.

Should the react docs contain clear information about how to structure your code for best compatibility with Fast Refresh?

Page

No response

Details

From what I've gathered, it's recommended that any file exporting a React component should not export anything else (e.g., utility functions, data) to ensure Fast Refresh functions properly, and I found eslint-plugin-react-refresh which exists to help enforce this rule.

I was surprised not to be able to find authoritative guidance on this in the official react docs.

• Is the advice I've seen in forums etc. correct, i.e. to export only 1 react component per file?
• Do the rules in eslint-plugin-react-refresh accurately reflect best practice as it stands in 2025?
• Should the react docs be more clear on what exactly is best practice in this respect?

(For background, I had to fix a number of issues when migrating our codebase (a few 10,000s loc) from preact to react and during this came across the plugin https://github.com/ArnaudBarre/eslint-plugin-react-refresh which I then enabled, which throws up many errors in our codebase (react/vite). I asked two experienced react developers if they comply with the rules as suggested by eslint-plugin-react-refresh and they seemed perplexed, suggesting that people don't structure things this way in real codebases — admittedly this is the most informal possible polling, but I couldn't point them to any particularly authoritative info to the contrary.)

As always, apologies if I have simply missed the relevant info in the docs.

[bhallstein]

Dupe of #5847 perhaps

[gaearon]

I agree official guidance would be helpful.

The linked rules seem a bit much. I wonder if these are specific to Vite or Parcel or some other implementations that are less forgiving. From what I recall, both Webpack and React Native (Metro) can handle non-React exports fine as long as there's something up the import chains to "contain" the update. In other words, if you have Foo and bla exports, and only Foo is a component, Fast Refresh will still work if Foo is only imported from some other file that itself only exports React components.

This is a bit galaxy brained but for an analogy, imagine a file edit is like a throw, an import is like a function call, and a module that only exports React components is like a catch. When you edit the file, it's like you're "throwing" from the place you edited. That "throw" (not literal) propagates up the module import chain. At each module boundary, it can be "caught" — but only if that module only exports React components. Otherwise it has to "keep propagating upwards" (cause if it's not just React components, then these new values/functions/objects may be needed someplace else). And then if it reaches the root module, it's game over — we can't safely Fast Refresh that.

Once this analogy clicks I think you'll find it relatively easy to think about what's OK to do. But I don't know how to express it less handwavey/metaphorically.

[bhallstein]

Many thanks @gaearon, appreciate the helpful analogy. If I understand you correctly the guidance as per /eslint-plugin-react-refresh are basically good, but there's not a pressing need to implement them religiously — though you mix exports all the way up your call stack (or a sizeable % of the way), then you might not get a great refresh experience.