Управление несколькими десятками пакетов в одном репозитории без автоматизации приводит к хаосу: ручное версионирование, конфликты межпакетных зависимостей, дублирование кода. Каждая новая фича требует синхронизации нескольких пакетов, что вручную занимает часы. 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 под ключ и убедитесь в эффективности автоматизации.