Next.js “Module not found: Can’t resolve ‘react'” happens when the app is installed with an incomplete or mismatched dependency tree, so the bundler starts compiling before React is actually available in node_modules.

In the reported repository, the application is a Next.js project, which depends on both react and react-dom. If either package is missing, installed under an incompatible version range, or skipped because of a lockfile/package-manager mismatch, Next.js fails during startup with the classic resolution error.

Understanding the Root Cause

This error means the module resolver cannot find the react package from the project where Next.js is running. In a healthy Next.js app, react, react-dom, and next must all be installed together and must be version-compatible.

The most common technical reasons are:

• react is missing from dependencies in package.json.
• The repo contains a lockfile from one package manager, but installation was done with another, producing a broken dependency graph.
• node_modules or the lockfile is stale or corrupted after switching Node.js versions or package managers.
• A deployment or local install used npm install –production or another workflow that skipped packages the app actually needs at runtime.
• The project uses versions of Next.js, React, and React DOM that do not align.

For this issue, the fix is usually not in application code. It is almost always a dependency installation and package metadata problem.

Step-by-Step Solution

Follow these steps in order. This fully resets the dependency tree and ensures the required React packages are present.

1. Verify that react and react-dom are declared

Open package.json and confirm you have entries similar to these under dependencies:

"dependencies": {
  "next": "13.x || 14.x || 15.x",
  "react": "^18.2.0",
  "react-dom": "^18.2.0"
}

If react or react-dom is missing, install them explicitly.

npm install react react-dom next

If the repository uses Yarn:

yarn add react react-dom next

If it uses pnpm:

pnpm add react react-dom next

2. Use the package manager that matches the repo

Check the project root for one of these lockfiles:

• package-lock.json – use npm
• yarn.lock – use Yarn
• pnpm-lock.yaml – use pnpm

Do not mix them. If the repo ships with yarn.lock, run Yarn instead of npm. If it ships with package-lock.json, use npm.

3. Remove stale installation artifacts

Delete the current install and lockfile artifacts that may be causing bad resolution.

rm -rf node_modules .next

If using npm:

rm -f package-lock.json
npm install

If using Yarn:

rm -f yarn.lock
yarn install

If using pnpm:

rm -f pnpm-lock.yaml
pnpm install

If you want to preserve the repo’s original lockfile, only delete node_modules and .next, then reinstall with the matching package manager.

4. Start the development server again

npm run dev

Or:

yarn dev

Or:

pnpm dev

5. If React still cannot be resolved, inspect installed versions

npm ls react react-dom next

This should show all three packages installed in the current project. If react shows as missing, the installation did not complete correctly or another workspace/package boundary is interfering.

6. Align versions if they are incompatible

For most current Next.js projects, a safe combination is:

npm install next@latest react@latest react-dom@latest

If the app depends on an older Next.js major version, install the React version that version expects instead of blindly forcing latest.

7. Confirm Node.js compatibility

Check the Node version in use:

node -v

If the project defines an engines field in package.json or documents a required Node version, switch to that version and reinstall dependencies. Tools like nvm help here.

nvm install 20
nvm use 20

Practical fix summary

For this specific class of issue, the fastest reliable recovery is:

rm -rf node_modules .next package-lock.json yarn.lock pnpm-lock.yaml
npm install
npm run dev

Then, if the repository clearly uses Yarn or pnpm, repeat with the correct package manager instead of npm.

Common Edge Cases

• Monorepo confusion: If the app lives inside a workspace, running install from the wrong directory can leave the Next.js app without local access to react. Always run commands from the app root or the workspace root expected by the repo.
• Peer dependency conflicts: A UI library may require a different React major version. Check install warnings carefully.
• Corrupted cache: If reinstalling does not work, clear the package manager cache.

npm cache clean --force

• Production-only install: In some CI or hosting setups, required packages may be skipped or hoisted incorrectly. Verify the platform is installing full app dependencies.
• Case-sensitive environment differences: Local macOS installs may appear to work while Linux CI fails because package paths and workspace assumptions are stricter there.
• Manual package.json edits without reinstall: Updating dependency entries does nothing until a fresh install is run.

FAQ

Why does Next.js need both react and react-dom?

Next.js uses react for component logic and react-dom for rendering. Missing either package can break compilation or runtime startup.

Can this happen even if package.json already lists react?

Yes. If node_modules is corrupted, the wrong package manager was used, or the lockfile pins a broken tree, the resolver can still fail even though package.json looks correct.

Should I commit the lockfile after fixing the issue?

Yes, if your team standard is to commit lockfiles. A committed, consistent lockfile helps prevent dependency drift and makes the React resolution issue less likely to reappear across machines and CI.

If you are debugging the repository from the issue, start by checking the declared dependencies, remove the existing install artifacts, and reinstall with the package manager the project actually expects. In most cases, that resolves the “Can’t resolve ‘react'” error immediately.