pnpm workspaces: общие пакеты и зависимости

На ноутбуке у Лейлы четырнадцать учебных проектов, и в каждом лежит собственная папка node_modules на сотни мегабайт — причём почти везде один и тот же React. Мурад предлагает другой путь: «Соберём web, api и общие пакеты в одном репозитории, а установкой и связыванием займётся pnpm». В этом уроке вы узнаете, чем pnpm отличается от npm, как устроена рабочая область (workspace) и как подключить код одного пакета в другой, не публикуя его в npm.

Почему pnpm

pnpm — менеджер пакетов для Node.js. Тот же package.json, тот же реестр npm, но другая схема хранения файлов. У неё три главные идеи.

1. Общее хранилище (store). Каждый файл каждой версии пакета лежит на диске один раз. В node_modules проекта файлы не копируются, а подключаются жёсткими ссылками. Жёсткая ссылка — это ещё одно имя того же файла: два адреса, одна комната. Поэтому второй проект с тем же react не занимает дополнительного места.
2. Строгий node_modules. В папку проекта pnpm кладёт только пакеты из его package.json, остальное прячет в node_modules/.pnpm. С npm код иногда импортирует пакет, который никто не объявлял, — он просто «лежал рядом». На чужой машине или в production такой код падает. pnpm ловит ошибку сразу.
3. Рабочие области из коробки. pnpm умеет объединять несколько пакетов одного репозитория в одну установку. Именно это нужно монорепозиторию.

💡 Хранилище должно лежать на том же диске, что и проект. На другом диске жёсткую ссылку сделать нельзя — pnpm копирует файлы, и выигрыш в месте пропадает.

Установка pnpm

На момент написания урока актуальна версия pnpm 12. Это самостоятельная программа: после установки ей не нужен Node.js (а ваши проекты по-прежнему запускаются на Node.js).

# any OS (Node.js 22.13+ is needed only to run this installer)
npx get-pnpm

# macOS / Linux without Node.js
curl -fsSL https://get.pnpm.io/install.sh | sh -

# check
pnpm -v

На Windows документация pnpm советует npx get-pnpm: Windows Defender иногда блокирует установочный скрипт. Команда pnpm -v покажет версию — она пригодится в package.json.

💡 В старых руководствах пишут corepack enable. Corepack входил в Node.js с версии 14.19 до 24, а начиная с Node.js 25 его нужно ставить отдельно (npm install -g corepack). Проще использовать установщик pnpm.

Рабочая область: pnpm-workspace.yaml

Рабочая область — это репозиторий, в котором pnpm видит несколько пакетов сразу. Нужен один файл в корне, который говорит, где их искать:

# pnpm-workspace.yaml (next to the root package.json)
packages:
  - "apps/*"
  - "packages/*"

Каждая папка внутри apps/ и packages/ со своим package.json становится отдельным пакетом. Приложения (apps/) запускают и выкладывают в интернет, пакеты (packages/) подключают к другим. Корневой package.json описывает сам репозиторий: