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