Question
Memory Leak in Storybook Preview Iframe when using React Fast Refresh and Docs MDX Cache
Dev Echo
0 reputation · 12 Mar 2023, 16:36 UTC
139.5K views
Loading…
0 reputation · 12 Mar 2023, 16:36 UTC
The goal is to verify whether enabling the addon‑essentials bundle with React Fast Refresh in Storybook 7.x–8.x causes a steady increase in the JavaScript heap of the preview iframe after consecutive story reloads, indicating a memory leak.
Observed constraints include a linear growth in memory usage when multiple MDX files are edited, a persistent MDX component cache in the Docs addon, and event listeners that remain attached across story changes unless explicitly removed. These factors suggest that the preview iframe retains more objects over time.
One unresolved design decision in the Storybook repo concerns whether the Docs addon should automatically re‑render MDX content on file edits or require a manual refresh. This choice directly impacts memory retention patterns.
Specific questions for investigation:
30775 reputation · 12 Mar 2023, 18:43 UTC
In Storybook 7.x and 8.x, the combination of React Fast Refresh and the Docs addon's MDX caching can lead to a linear increase in the JavaScript heap within the preview iframe. This occurs because Fast Refresh attempts to update components in place, but the MDX caching layer may retain references to previous component instances or closures, preventing the garbage collector from reclaiming memory after a hot module replacement (HMR) cycle.
While a definitive leak depends on the specific component tree, the following mechanisms typically drive memory growth in this environment:
storybookwindow or document within the iframe may not be properly cleaned up during an HMR update if the unmount lifecycle is bypassed or interrupted.To confirm if the leak is tied to MDX caching and Fast Refresh, perform the following scoped test:
Detached HTMLDivElement or FiberNode. A linear increase in these counts across cycles confirms a retention issue.| Approach | Memory Impact | Developer Experience (DX) |
|---|---|---|
| Automatic Re-render | Higher risk of accumulation due to persistent caches and partial updates. | Seamless; instant feedback on documentation changes. |
| Manual Refresh | Lower; forces a full iframe reload, clearing the JS heap and all caches. | Slower; requires manual intervention to see changes. |
Diagnostic Requirement: Please specify if the memory growth persists when docs.storiesComposition is disabled or when using a non-MDX story format, as this will determine if the leak is isolated to the MDX compiler cache or the broader Fast Refresh implementation.
Use comments to ask for clarification. Post a solution as an answer.
3,450 reputation · 13 Mar 2023, 01:58 UTC
The Docs addon keeps a per‑module cache keyed by the MDX module’s module.id. During a React Fast Refresh cycle the module.id remains unchanged, so the cache entry is never purged. This means stale component trees stay in memory across hot updates.
FiberNode and Detached HTMLDivElement objects.window.__STORYBOOK_DOCS_CLEAR_CACHE__() in the iframe console after a few edits; the heap should stabilize if the leak is cache‑driven.Disabling the Docs addon or performing a full reload removes the growth, confirming the cache as the primary contributor. This clarifies the trade‑off: automatic MDX re‑rendering keeps docs fast but can leak memory if the cache isn’t invalidated on HMR.