Управление несколькими десятками пакетов в одном репозитории без автоматизации приводит к хаосу: ручное версионирование, конфликты межпакетных зависимостей, дублирование кода. Каждая новая фича требует синхронизации нескольких пакетов, что вручную занимает часы. Lerna решает эти проблемы, предоставляя единый интерфейс для версионирования, сборки и публикации. Наш опыт насчитывает более пятидесяти monorepo-проектов, и Lerna остается основным выбором для библиотек и утилит, публикуемых в npm. Это фундамент для масштабирования кодовой базы без боли. Ниже — детальный разбор того, как мы настраиваем Lerna под ключ: от анализа до CI/CD и документации. Получите консультацию инженера, чтобы оценить, подходит ли Lerna для вашего проекта.
Почему Lerna, а не Turborepo или Nx?
Lerna имеет смысл, когда проект — библиотека или набор пакетов, которые публикуются в npm. Требуется автоматическое управление версиями (semver) и CHANGELOG. Команда небольшая, сложная инфраструктура избыточна. Для закрытого продукта без публикации — лучше Turborepo или Nx. Lerna 6+ возродился под управлением Nrwl с опциональным Nx под капотом для кеширования и параллельного выполнения задач. Экономия времени на сборке достигает 50% при 20+ пакетах.
Настройка Lerna: пошаговый процесс
Анализ и конфигурация
Начинаем с определения режима: independent или fixed. Согласовываем стек, CI-провайдера, менеджер пакетов. pnpm ускоряет установку на 30% и экономит до 50% дискового пространства за счет дедупликации. Инициализируем Lerna, настраиваем lerna.json, workspaces, подключаем commitlint и husky для контроля conventional commits. Обучение команды занимает 2–3 часа.
npx lerna init --packages="packages/*" --independent Пример lerna.json:
{
"$schema": "node_modules/lerna/schemas/lerna-schema.json",
"version": "independent",
"npmClient": "pnpm",
"command": {
"publish": {
"conventionalCommits": true,
"createRelease": "github",
"message": "chore(release): publish",
"registry": "https://registry.npmjs.org",
"allowBranch": ["main", "next"]
},
"version": {
"conventionalCommits": true,
"conventionalChangelogConfig": "@conventional-changelog/conventionalcommits",
"changelogPreset": "angular",
"gitTagVersion": true,
"push": true
},
"bootstrap": {
"npmClientArgs": ["--no-package-lock"]
}
},
"useWorkspaces": true,
"useNx": true
}Структура репозитория
Организуем пакеты в packages/: например, button, input, modal. Каждый пакет — независимая единица с tsconfig и тестами. Для документации используем apps/docs (Storybook).
my-ui-library/
├── packages/
│ ├── button/
│ ├── input/
│ ├── modal/
│ ├── table/
│ └── theme/
├── apps/
│ └── docs/
├── package.json
├── lerna.json
└── pnpm-workspace.yamlУправление версиями и публикация
| Команда | Описание |
|---|---|
lerna changed | Показывает изменившиеся пакеты |
lerna version | Интерактивно обновляет версии |
lerna version --conventional-commits --yes | Автоматически по conventional commits |
lerna publish from-package | Публикует все неопубликованные пакеты |
lerna publish from-git | Публикует пакеты, для которых созданы git-теги |
При запуске lerna version происходит определение изменившихся пакетов, предложение новых версий по semver, обновление package.json и межпакетных зависимостей, генерация CHANGELOG.md, создание git-коммита и тегов. Весь процесс занимает менее 5 минут для 20 пакетов.
Как Lerna интегрируется с CI/CD?
Пайплайн строится на GitHub Actions или GitLab CI. Ключевой момент — автоматическая публикация только при слиянии в main. Используем lerna version --conventional-commits --yes для генерации версии и changelog, затем lerna publish from-git для публикации. Для масштабирования включаем useNx: true — это дает кеширование и параллельное выполнение задач, сокращая время сборки до 10 минут даже для 50+ пакетов. В результате релиз занимает 15 минут вместо нескольких часов, что снижает затраты на CI/CD на 30–40%.
# .github/workflows/release.yml
name: Release
on:
push:
branches: [main]
permissions:
contents: write
packages: write
jobs:
release:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
token: ${{ secrets.GITHUB_TOKEN }}
- uses: pnpm/action-setup@v3
- uses: actions/setup-node@v4
with:
node-version: 20
registry-url: 'https://registry.npmjs.org'
- run: pnpm install --frozen-lockfile
- name: Build all packages
run: npx lerna run build
- name: Version and publish
run: |
git config user.email "[email protected]"
git config user.name "CI Bot"
npx lerna version --conventional-commits --yes --no-push
npx lerna publish from-git --yes
env:
NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}Запуск задач с Nx под капотом
Lerna 6+ использует Nx для умного запуска:
npx lerna run build npx lerna run test --since=main npx lerna run build --scope=@acme/modal --include-dependents Кеширование Nx позволяет повторно использовать результаты сборки, экономя до 70% времени при повторных запусках. Это особенно важно для крупных monorepo с сотнями пакетов.
Independent или fixed mode?
Для библиотек компонентов или утилит, которые выпускаются асинхронно, independent mode — единственный разумный выбор. Каждый пакет версионируется независимо, что позволяет исправлять баги в одном пакете без затрагивания других. В fixed mode, как в React или Vue, все пакеты синхронизированы — это проще, но менее гибко. Мы рекомендуем independent mode для проектов с разной частотой релизов. Экономия времени на согласование версий составляет 2–3 часа в неделю.
Что входит в настройку
- Полностью сконфигурированный monorepo с Lerna и выбранным менеджером пакетов (pnpm/npm/yarn)
- CI/CD пайплайн (GitHub Actions или GitLab CI) для автоматической публикации при слиянии в main
- Документация процесса релиза с правилами conventional commits
- Онбординг команды (демо-сессия 2–4 часа)
- Поддержка в течение 2 недель после внедрения: исправление ошибок, консультации
Окупаемость такой настройки — менее 3 месяцев за счет сокращения ручного труда и ошибок при релизе.
Типичные сложности
При обновлении версии через lerna version зависимость может не обновиться, если указан мягкий диапазон (^ или ~). Флаг --force-publish обновляет все пакеты принудительно, а хардкодные версии (без caret) гарантируют обновление. CHANGELOG может дублировать записи — используйте --changelog-include-commits-root-path если нужны корневые коммиты. Публикация на CI может упасть из-за npm publish --dry-run в .npmrc — убедитесь, что dry-run=false в CI окружении.
Сроки и стоимость
Настройка Lerna для набора npm-пакетов с нуля занимает от 2 до 5 дней в зависимости от сложности. Стоимость рассчитывается индивидуально. Свяжитесь с нами для оценки вашего проекта и получите консультацию инженера с многолетним опытом в JavaScript-экосистеме. Закажите настройку monorepo под ключ и убедитесь в эффективности автоматизации.
