A library fails to build because react has no useSyncExternalStore
export 'useSyncExternalStore' (imported as 'React') was not found in 'react'Short answer
useSyncExternalStore is a hook that React added in version 18. If your project resolves an older react, or a library brings its own older copy, the import has nothing to bind to and the build fails. Run npm ls react to see every copy, then move to React 18 or newer, or one single copy.
Fix it fast
1Find out which cause you have
List every copy of react your project resolves. The version printed here is the one the failing import is looking at.
npm ls react2Match what you see, then jump to its fix
What does the error look like?
export 'useSyncExternalStore' (imported as 'React') was not found in 'react'
Cause 1 of 2
Your project uses a React older than 18
1Check
The React 18 release notes list useSyncExternalStore as a new hook, intended for libraries that read external state. A library that calls it needs React 18 or newer; on React 17 the named import does not exist.
npm ls react
grep '"react"' package.json2Fix
Upgrade React to 18 or newer, together with the renderer (react-dom on the web). In a React Native app, the renderer is react-native itself, so keep react and react-native at versions that belong together and upgrade both.
npm install react@latest react-dom@latest3Verify
Only one version of react at 18 or newer is listed, and the bundler starts without the warning.
npm ls reactConfirmed by react.dev
Cause 2 of 2
A dependency installs its own older copy of react
1Check
React expects the app and its renderer to resolve the same react module. A library that lists react as a normal dependency instead of a peer dependency can pull in a second copy. Find which package asks for it.
npm ls react
npm explain react2Fix
Make the whole tree use one version. With npm, add an override in the root package.json that forces the version you installed, then reinstall.
{
"overrides": {
"react": "$react"
}
}3Verify
A fresh install shows a single react entry.
rm -rf node_modules package-lock.json
npm install
npm ls reactConfirmed by react.dev
How do I stop it coming back?
- Read the peerDependencies of a library before you install it; if it needs React 18, plan the upgrade first.
- Keep react and react-dom (or react-native) upgrades in one commit so the renderer never lags behind.
- Run npm ls react in CI and fail the build when more than one copy appears.
Sources
How was this page made?
I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.
Which stack is behind this page?
Projects of mine built on the same technologies:
- TaxiDexMy own multi-tenant taxi dispatch SaaS: API, dispatcher portal, driver and passenger apps, and the servers underneath.
- QistLockA NestJS and React SaaS driving an Android Device Owner agent that locks financed phones when payments lapse.
- TaskvareA task and project-management suite: React on the web, Flutter on mobile, TypeScript underneath.
Related fixes
Web apps
Axios get works with a URL string but ignores the object passed as the second argument
The server log shows a GET with no query string
axios.get takes a URL and an optional config object.
3 causes, each with a fixWeb apps
Expo app never leaves the splash screen
App shows the splash screen forever and no error appears
After SplashScreen.preventAutoHideAsync() the splash stays until you hide it yourself.
3 causes, each with a fixWeb apps
NativeViewGestureHandler must be used as a descendant of GestureHandlerRootView
Error: NativeViewGestureHandler must be used as a descendant of GestureHandlerRootView. Otherwise the gestures will not be recognized.
react-native-gesture-handler only recognises gestures inside GestureHandlerRootView.
3 causes, each with a fixWeb apps
React Hook "useState" cannot be called at the top level, or in a function that is not a component
The lint points at a useState line inside a helper function, an onClick handler or the top of a module
The lint rule found a hook outside a component or custom hook.
3 causes, each with a fixWeb apps
React: Maximum update depth exceeded or Too many re-renders
Maximum update depth exceeded
React stops a component that sets state again and again without end.
3 causes, each with a fixWeb apps
React Native says the application has not been registered
Application has not been registered
The native side asks JavaScript to run an app name that JavaScript never registered.
3 causes, each with a fix