Next.js не находит React: что проверить перед переустановкой зависимостей

Module not found: Can't resolve 'react' - ошибка, которая останавливает сборку Next.js ещё до запуска приложения. При этом React может быть прописан в package.json, а команда установки зависимостей - завершаться без ошибок. Проверять в такой ситуации нужно не только наличие пакета, но и то, откуда сборщик пытается его загрузить.

Когда package.json вводит в заблуждение

Запись в package.json сообщает менеджеру пакетов, какая зависимость нужна проекту. Она не подтверждает, что пакет установлен в текущем окружении. После переключения ветки, изменения lock-файла или переноса приложения конфигурация и фактически установленные зависимости могут перестать соответствовать друг другу.

В проекте на npm начните с проверки дерева зависимостей:

//bash

npm ls react react-dom next

Если npm сообщает, что React отсутствует или помечен как missing, сравните вывод с package.json. Если зависимость не объявлена, добавьте её в проект. Если она указана, но не установлена, восстановите зависимости из актуального манифеста и lock-файла:

//bash

npm install

После этого повторите запуск. Обновлять React и Next.js до последних версий только ради устранения этой ошибки не стоит: так можно получить новую проблему совместимости вместо исходной.

Почему каталог запуска имеет значение

В Next.js-проекте важно, где именно выполняются команды. Особенно это заметно в монорепозиториях, где несколько приложений используют общий репозиторий.

Предположим, структура проекта выглядит так:

//text

project/
├── package.json
├── package-lock.json
└── apps/
    └── web/
        ├── package.json
        └── app/
            └── page.tsx

Если запускать команды из корня, а само приложение настраивать как отдельный workspace, результаты проверки могут относиться не к тому пакету, который собирается. Поэтому сначала перейдите в каталог приложения и проверьте его конфигурацию:

//bash

cd apps/web
npm ls react

Это не универсальная команда для любой монорепы: если зависимости управляются из корня через workspaces, проверку следует выполнять с учётом настроек используемого менеджера пакетов. Суть в том, чтобы проверить именно окружение приложения Next.js.

Node.js видит React, а сборка всё равно падает

Проверить, может ли Node.js разрешить импорт React из текущего каталога, можно командой:

//bash

node -p "require.resolve('react')"

Если команда возвращает путь к файлу, пакет доступен механизму разрешения модулей Node.js в этом контексте. Если возникает ошибка, нужно разбираться с установкой зависимостей или каталогом запуска.

Однако успешная проверка не гарантирует, что Next.js соберёт приложение. Сборщик использует собственный процесс разрешения импортов и учитывает конфигурацию проекта. В частности, Turbopack ограничивает поиск файлов корневым каталогом приложения. Поэтому пакет или связанная библиотека, расположенные за пределами этого корня, могут оказаться недоступны для сборки. <Link url="https://nextjs.org/docs/app/api-reference/config/next-config-js/turbopack" title="Это поведение описано в документации Turbopack"/>.

Когда стоит проверять next.config

Если зависимости установлены, рабочий каталог выбран правильно, но ошибка сохраняется, посмотрите конфигурацию сборщика. В next.config.ts настройка turbopack.root задаёт корневую директорию для поиска файлов и модулей.

Например, если приложение находится во вложенном каталоге и действительно должно обращаться к файлам выше него, корень можно настроить явно:

//ts

import path from 'node:path'
import type { NextConfig } from 'next'

const nextConfig: NextConfig = {
  turbopack: {
    root: path.resolve(__dirname, '../..'),
  },
}

export default nextConfig

Этот вариант подходит не каждому проекту: путь зависит от расположения файла конфигурации и структуры репозитория. Менять root без подтверждения проблемы не нужно. Если ошибка появилась после переноса приложения или подключения локальной библиотеки, сначала проверьте, находится ли нужный код внутри текущего корня сборки.

Если ошибка появляется только на сервере

Когда локальная разработка работает, а CI или Docker выдаёт Can't resolve 'react', сравните условия сборки. Важны рабочий каталог, команда установки, используемый lock-файл и наличие всех необходимых манифестов. Контейнер может собираться в чистом окружении, где нет зависимостей, оставшихся от предыдущих запусков.

Не удаляйте package-lock.json в надежде исправить проблему: это может изменить версии всего дерева зависимостей. Сначала установите, почему текущее окружение не соответствует ожидаемому.

Сообщение Can't resolve 'react' не означает, что нужно обязательно переустанавливать React. Оно указывает на конкретный сбой разрешения импорта. Причина обнаруживается при сравнении конфигурации проекта, фактически установленных пакетов и условий, в которых работает сборщик.