{"record":{"id":"ecf02b5a96af7e82","repo":"mobxjs/mobx","slug":"mobx-react-lite-requires-react-18-or-later","errorCode":null,"errorMessage":"mobx-react-lite requires React 18 or later","messagePattern":"mobx-react-lite requires React 18 or later","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"packages/mobx-react-lite/src/utils/assertEnvironment.ts","lineNumber":5,"sourceCode":"import { _getGlobalState } from \"mobx\"\nimport { useState, useSyncExternalStore } from \"react\"\n\nif (!useState || !useSyncExternalStore) {\n    throw new Error(\"mobx-react-lite requires React 18 or later\")\n}\nif (!(_getGlobalState?.()?.version >= 7)) {\n    throw new Error(\"mobx-react-lite requires mobx at least version 7 to be available\")\n}\n","sourceCodeStart":1,"sourceCodeEnd":10,"githubUrl":"https://github.com/mobxjs/mobx/blob/01211a698b64ea94de8e5f276ff8235fcf8ddf96/packages/mobx-react-lite/src/utils/assertEnvironment.ts#L1-L10","documentation":"mobx-react-lite relies on `useState` and especially `useSyncExternalStore` from React, which only exist in React 18+. At module load, if either hook is falsy, this error throws immediately, meaning the library can never be used in that environment. It is an environment/version compatibility guard evaluated once on import.","triggerScenarios":"Importing `mobx-react-lite` in a project with react/react-dom < 18; running against a React shim that omits `useSyncExternalStore`; misconfigured aliases resolving `react` to an old or stub build.","commonSituations":"Legacy React 16/17 apps after upgrading mobx-react-lite; bundler aliasing `react` to a UMD or mock build in tests; monorepos where a dependency pins an old React copy.","solutions":["Upgrade react and react-dom to 18 or later (`npm install react@18 react-dom@18`).","Check for React 18's `useSyncExternalStore`; if using React 18 with a shim (e.g. react-native web old version), upgrade the shim.","Fix bundler/test aliases (jest moduleNameMapper, webpack alias) so `react` resolves to the installed React 18 build, not a stub.","If stuck on React 17, downgrade to mobx-react-lite 3.x which supports older React."],"exampleFix":"// before (package.json)\n\"react\": \"^17.0.2\"\n\n// after\n\"react\": \"^18.2.0\",\n\"react-dom\": \"^18.2.0\"","handlingStrategy":"validation","validationCode":"import * as React from 'react'\nif (!React.useState || !React.useSyncExternalStore) {\n  throw new Error('mobx-react-lite needs React 18+; found: ' + (React.version || 'unknown'))\n}","typeGuard":"const isReact18Plus = (R) => typeof R?.useState === 'function' && typeof R?.useSyncExternalStore === 'function'","tryCatchPattern":"// module-load throw: wrap the first import site if dynamically loading\ntry {\n  const m = await import('mobx-react-lite')\n} catch (e) {\n  if (String(e.message).includes('requires React 18')) {\n    // surface dependency upgrade requirement\n  }\n  throw e\n}","preventionTips":["Pin react/react-dom to ^18 in package.json and enforce with engine checks.","In monorepos, verify a single React copy with `npm ls react`.","Check jest moduleNameMapper/webpack aliases don't stub react for app code.","Smoke-test the app entry in CI on React 18 before upgrading mobx-react-lite."],"tags":["react","mobx-react-lite","version-compatibility","environment"],"backgroundTag":"react-version-too-old","analyzedSha":"01211a698b64ea94de8e5f276ff8235fcf8ddf96","analyzedAt":"2026-08-28T22:10:08.831Z","schemaVersion":2},"datasetVersion":"2026-08-29T02:17:18.158Z"}