Как использовать локальные npm‑пакеты в NextJS

Когда вы работаете с локальными пакетами npm в проекте Next.js без публикации в npm, проблема обычно связана с ошибками разрешения модулей, которые можно решить несколькими способами. Самыми надёжными решениями являются использование npm‑рабочих пространств, настройка Next.js для корректного разрешения модулей или изменение структуры рабочего пространства.

Содержание

• Понимание проблемы
• Решение 1: Использование npm‑рабочих пространств
• Решение 2: Настройка Next.js для локальных пакетов
• Решение 3: Альтернативные подходы
• Распространённые проблемы и устранение неполадок

Понимание проблемы

Ошибка «Module not found», которую вы видите, возникает потому, что Next.js имеет собственную систему разрешения модулей, отличающуюся от стандартного разрешения Node.js. Даже если в node_modules вы видите символическую ссылку и IDE распознаёт импорты, сборщик Next.js (Webpack) не может корректно разрешить эти локальные пакеты во время сборки.

Согласно документации Next.js, это происходит, когда модули недоступны в ожидаемых местах или система сборки не может правильно проследить зависимости модуля.

Решение 1: Использование npm‑рабочих пространств

Самый надёжный способ — использовать npm‑рабочие пространства, специально предназначенные для управления локальными пакетами в монорепозитории.

Пошаговая реализация

1. Инициализируйте корневой каталог как рабочее пространство:

   bash

   cd /path/to/your/project
   npm init -y
   

2. Настройте рабочие пространства в package.json:

   json

   {
     "name": "my-project",
     "version": "1.0.0",
     "private": true,
     "workspaces": [
       "packages/*",
       "apps/*"
     ]
   }
   

3. Создайте структуру каталогов packages:

   my-project/
   ├── packages/
   │   ├── test-sample-api/
   │   │   ├── package.json
   │   │   ├── src/
   │   │   └── dist/
   │   └── my-next-app/
   │       ├── package.json
   │       ├── next.config.js
   │       └── pages/
   

4. Установите зависимости в корне рабочего пространства:

   bash

   npm install
   

Этот подход, как отмечено в обсуждениях Stack Overflow, гарантирует, что все пакеты используют общие зависимости, и Next.js сможет корректно разрешить локальные модули.

Решение 2: Настройка Next.js для локальных пакетов

Если вы предпочитаете сохранить текущую структуру, можно настроить Next.js для более надёжного разрешения локальных зависимостей.

Конфигурация Next.js

Добавьте следующее в next.config.js:

const path = require('path');

const nextConfig = {
  // Добавьте эту настройку для разрешения локальных модулей
  outputFileTracingRoot: path.join(__dirname, '../'),

  // Опционально: настройка резолвера Webpack
  webpack: (config, { dev, isServer }) => {
    config.resolve.alias = {
      ...config.resolve.alias,
      'test-sample-api': path.join(__dirname, '../test-sample-api/dist'),
    };
    return config;
  },
};

module.exports = nextConfig;

Эта конфигурация, предложенная в ответах Stack Overflow, помогает Next.js находить ваши локальные пакеты, явно определяя пути разрешения.

Конфигурация package.json

Убедитесь, что у вашего локального пакета корректный package.json с правильными точками входа:

{
  "name": "test-sample-api",
  "version": "1.0.0",
  "main": "dist/index.js",
  "module": "dist/index.esm.js",
  "types": "dist/index.d.ts",
  "files": ["dist"]
}

Решение 3: Альтернативные подходы

Ручное создание символических ссылок

Если рабочие пространства не подходят, можно вручную создать символические ссылки:

# Перейдите в ваш проект Next.js
cd my-next-app

# Создайте символическую ссылку в node_modules
ln -s ../test-sample-api node_modules/test-sample-api

Использование Yarn или pnpm

Менеджеры пакетов, такие как Yarn и pnpm, лучше обрабатывают локальные зависимости:

# С Yarn
yarn add ../test-sample-api --cwd my-next-app

# С pnpm
pnpm add ../test-sample-api

Согласно обсуждениям GitHub, эти менеджеры пакетов часто более надёжно разрешают локальные зависимости в сложных сценариях.

Распространённые проблемы и устранение неполадок

Проблемы с кэшем

Очистите кэш Next.js и пересоберите:

rm -rf .next
rm -rf node_modules/.cache
npm install
npm run build

Как отмечено в ответах Stack Overflow, очистка кэша Webpack часто решает проблемы разрешения модулей.

Конфликты зависимостей

Убедитесь, что ваш локальный пакет и приложение Next.js используют совместимые версии общих зависимостей, таких как React и сам Next.js. Обсуждения в GitHub issue показывают, что конфликты peer‑зависимостей часто возникают при использовании локальных React‑библиотек.

Разрешение путей

Проверьте, что ваш локальный пакет компилируется в правильное место и что пути импортов соответствуют конфигурации сборки. Как отмечено в анализе Omi AI, неправильные пути к модулям часто вызывают эти ошибки.

Источники

1. Документация Next.js – Module Not Found
2. Stack Overflow – Next.js webpack module not found in npm local package
3. Stack Overflow – ERROR MODULE NOT FOUND whenever I try to run ‘npm run dev’ using Next.js
4. Stack Overflow – How to fix Next.js Vercel deployment module not found error
5. GitHub Discussion – Module Not Found ERRORS
6. Stack Overflow – Next.js module not found only when importing a simple sum function from my own npm library
7. GitHub Issue – Module not found: Can’t resolve ‘react’ when importing local library with React as peerDependency
8. Omi AI – Module not found: Can’t resolve ‘react’ in Next.js
9. GitHub Issue – Nextjs 15: Importing git modules issue
10. GitHub Issue – Cannot find module error when package directory name ends with ‘next’

Вывод

Самый эффективный способ работы с локальными пакетами npm в Next.js без публикации — использовать npm‑рабочие пространства, которые обеспечивают структурированный подход к управлению локальными зависимостями. Этот метод устраняет проблемы разрешения модулей, гарантируя, что все пакеты используют одну и ту же структуру зависимостей и могут корректно разрешаться во время сборки.

Ключевые рекомендации:

1. Используйте npm‑рабочие пространства для разработки в стиле монорепозитория с локальными пакетами.
2. Настройте Next.js с outputFileTracingRoot и алиасами Webpack, если предпочитаете отдельные каталоги.
3. Регулярно очищайте кэши сборки, чтобы избежать устаревших ссылок на модули.
4. Убедитесь в корректной конфигурации package.json с правильными точками входа.
5. Рассмотрите альтернативные менеджеры пакетов (Yarn, pnpm) для более надёжного управления локальными зависимостями.

Внедрив эти решения, вы сможете разрабатывать локальные пакеты вместе с приложением Next.js без необходимости публиковать каждый изменённый пакет в npm, что значительно ускорит ваш цикл разработки.