{"record":{"id":"cac7f4292e43a9c1","repo":"facebook/react","slug":"react-refresh-runtime-should-not-be-included-in-th","errorCode":null,"errorMessage":"React Refresh runtime should not be included in the production bundle.","messagePattern":"React Refresh runtime should not be included in the production bundle\\.","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"packages/react-refresh/src/ReactFreshRuntime.js","lineNumber":36,"sourceCode":"import type {ReactNodeList} from 'shared/ReactTypes';\n\nimport {REACT_MEMO_TYPE, REACT_FORWARD_REF_TYPE} from 'shared/ReactSymbols';\n\ntype Signature = {\n  ownKey: string,\n  forceReset: boolean,\n  fullKey: string | null, // Contains keys of nested Hooks. Computed lazily.\n  getCustomHooks: () => Array<Function>,\n};\n\ntype RendererHelpers = {\n  scheduleRefresh: ScheduleRefresh,\n  scheduleRoot: ScheduleRoot,\n  setRefreshHandler: SetRefreshHandler,\n};\n\nif (!__DEV__) {\n  throw new Error(\n    'React Refresh runtime should not be included in the production bundle.',\n  );\n}\n\n// In old environments, we'll leak previous types after every edit.\nconst PossiblyWeakMap = typeof WeakMap === 'function' ? WeakMap : Map;\n\n// We never remove these associations.\n// It's OK to reference families, but use WeakMap/Set for types.\nconst allFamiliesByID: Map<string, Family> = new Map();\nconst allFamiliesByType: WeakMap<any, Family> | Map<any, Family> =\n  new PossiblyWeakMap();\nconst allSignaturesByType: WeakMap<any, Signature> | Map<any, Signature> =\n  new PossiblyWeakMap();\n// This WeakMap is read by React, so we only put families\n// that have actually been edited here. This keeps checks fast.\nconst updatedFamiliesByType: WeakMap<any, Family> | Map<any, Family> =\n  new PossiblyWeakMap();","sourceCodeStart":18,"sourceCodeEnd":54,"githubUrl":"https://github.com/facebook/react/blob/eafeac097ba51e1eab809c07102126bd5f8e5425/packages/react-refresh/src/ReactFreshRuntime.js#L18-L54","documentation":"react-refresh/runtime (ReactFreshRuntime) throws at module-evaluation time when it is compiled with __DEV__ === false. The runtime maintains the module registry and patches React's internals purely for Fast Refresh; shipping it in a production bundle is always a bundling mistake, so the module hard-fails on load instead of silently bloating (or breaking) the production artifact.","triggerScenarios":"A production build that imports react-refresh/runtime — for example bootstrap code like `if (module.hot) { require('react-refresh/runtime'); ... }` where the guard does not also exclude prod; the bundler resolving __DEV__ to false (correct) while the module itself still gets included via an unconditional import in a shared entry file.","commonSituations":"Manually wiring Fast Refresh in custom webpack/esbuild setups without the official plugin's prod gating; a shared setup file (app bootstrap, jest setup) imported into the production entry; stale bundle cache where a dev-only import leaked into a prod artifact.","solutions":["Gate every react-refresh import and setup call behind if (process.env.NODE_ENV !== 'production')","Use the official integrations (@pmmmwh/react-refresh-webpack-plugin or framework defaults), which exclude the runtime from production builds","Verify the fix by grepping the prod bundle for 'React Refresh runtime should not be included' — zero hits expected","Move react-refresh to devDependencies so a prod reference fails at install time rather than at runtime"],"exampleFix":"// before (entry.js, always executed)\nrequire('react-refresh/runtime');\nrequire('react-refresh/runtime').injectIntoGlobalHook(window);\n\n// after\nif (process.env.NODE_ENV !== 'production') {\n  const refresh = require('react-refresh/runtime');\n  refresh.injectIntoGlobalHook(window);\n}","handlingStrategy":"validation","validationCode":"if (process.env.NODE_ENV !== 'production') {\n  const refresh = require('react-refresh/runtime');\n  refresh.injectIntoGlobalHook(window);\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Keep react-refresh in devDependencies and gate all its imports behind a NODE_ENV check","Grep the production bundle for 'React Refresh runtime' before shipping as a CI check","Prefer official integrations whose prod builds already exclude the runtime"],"tags":["react-refresh","fast-refresh","production-bundle","bundler","devtools"],"backgroundTag":"dev-only-code-in-production-bundle","analyzedSha":"eafeac097ba51e1eab809c07102126bd5f8e5425","analyzedAt":"2026-08-21T22:01:08.818Z","schemaVersion":2},"datasetVersion":"2026-08-21T23:17:16.201Z"}