Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Next.js and React

A library fails to build because react has no useSyncExternalStore

Errorexport '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.

  • Applies to React 18, React 19, React Native 0.7x, npm 10
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 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 react
  2. 2Match what you see, then jump to its fix

    1. 1npm ls react shows react@17 or older at the top of the treeYour project uses a React older than 18Fix
    2. 2npm ls react lists more than one react, one of them nested under a libraryA dependency installs its own older copy of reactFix

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.json

2Fix

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@latest

3Verify

Only one version of react at 18 or newer is listed, and the bundler starts without the warning.

npm ls react

Confirmed by react.dev

Did this fix it?

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 react

2Fix

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 react

Confirmed by react.dev

Did this fix it?

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:

Related fixes

Web 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 fix

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.