{"record":{"id":"21e2c9b36688a902","repo":"withastro/astro","slug":"unsupported-react-version-majorversion-21e2c9","errorCode":null,"errorMessage":"Unsupported React version: ${majorVersion}.","messagePattern":"Unsupported React version: (.+?)\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/integrations/react/src/index.ts","lineNumber":176,"sourceCode":"\t\t\t\t\tfinalOptions.optimizeDeps!.include.push(reactConfig.client);\n\t\t\t\t}\n\t\t\t}\n\n\t\t\treturn finalOptions;\n\t\t},\n\t};\n}\n\nexport default function ({\n\tinclude,\n\texclude,\n\tbabel,\n\texperimentalReactChildren,\n\texperimentalDisableStreaming,\n}: ReactIntegrationOptions = {}): AstroIntegration {\n\tconst majorVersion = getReactMajorVersion();\n\tif (!isSupportedReactVersion(majorVersion)) {\n\t\tthrow new Error(`Unsupported React version: ${majorVersion}.`);\n\t}\n\tconst versionConfig = versionsConfig[majorVersion];\n\n\treturn {\n\t\tname: '@astrojs/react',\n\t\thooks: {\n\t\t\t'astro:config:setup': ({ command, addRenderer, updateConfig, injectScript }) => {\n\t\t\t\taddRenderer(getRenderer(versionConfig));\n\t\t\t\tupdateConfig({\n\t\t\t\t\tvite: getViteConfiguration(\n\t\t\t\t\t\t{ include, exclude, babel, experimentalReactChildren, experimentalDisableStreaming },\n\t\t\t\t\t\tversionConfig,\n\t\t\t\t\t),\n\t\t\t\t});\n\t\t\t\tif (command === 'dev') {\n\t\t\t\t\tconst preamble = FAST_REFRESH_PREAMBLE.replace(`__BASE__`, '/');\n\t\t\t\t\tinjectScript('before-hydration', preamble);\n\t\t\t\t}","sourceCodeStart":158,"sourceCodeEnd":194,"githubUrl":"https://github.com/withastro/astro/blob/52e6c34790cc8ac4e69e6135ace06049867e5c4a/packages/integrations/react/src/index.ts#L158-L194","documentation":"The @astrojs/react integration itself resolves react-dom's version at import/creation time and looks it up in versionsConfig (React 17, 18, 19 only) to pick matching client/server entrypoints. An unsupported major throws before any hook runs, so astro dev/build fails during config setup.","triggerScenarios":"Starting astro dev or astro build with react-dom 16, an experimental major, or react-dom missing (version parse yields NaN); mixed react/react-dom versions where the resolved react-dom is unsupported.","commonSituations":"Upgrading to a brand-new React major before the adapter supports it; lockfile drift after a partial upgrade; CI installing react only; workspace hoisting an old react-dom.","solutions":["Pin both react and react-dom to a supported major (17, 18, or 19), keeping them on the same version","Reinstall to fix lockfile drift: remove node_modules and the lockfile entry, then fresh install","Update @astrojs/react for support of newer React majors as they land"],"exampleFix":"# before\nreact@16 react-dom@16\n# after\nreact@^18 react-dom@^18","handlingStrategy":"type-guard","validationCode":"import { version } from 'react-dom';\nconst major = Number(/\\d+\\./.exec(version)?.[0]);\nif (![17, 18, 19].includes(major)) {\n  throw new Error(`Fix react-dom before building: got ${version}, need 17/18/19`);\n}","typeGuard":"function isSupportedReactMajor(major: number): major is 17 | 18 | 19 {\n  return major in { 17: 1, 18: 1, 19: 1 };\n}","tryCatchPattern":null,"preventionTips":["Upgrade react and react-dom together with @astrojs/react","Verify react-dom is installed and hoisted in monorepos before astro dev","Fail CI on unsupported majors with an explicit preflight check"],"tags":["react","version","adapter","config"],"backgroundTag":"unsupported-library-version","analyzedSha":"52e6c34790cc8ac4e69e6135ace06049867e5c4a","analyzedAt":"2026-08-18T18:48:03.901Z","contentChangedAt":"2026-08-18T18:48:03.901Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}