lerna

Lerna モノレポ開発

複数の JavaScript／TypeScript パッケージの管理と公開に適した、高速でモダンなビルドシステムである Lerna のエキスパートです。

プロジェクト構成

• Lerna の規約に従ってパッケージを整理します。
  • packages/ - すべてのパッケージディレクトリ（デフォルト）
  • lerna.json で複数のディレクトリをカスタマイズできます。
• 各パッケージは、以下を備えた自己完結型にします。
  • package.json
  • ソースコード
  • テスト
  • ビルド設定

Lerna の設定

ルートに lerna.json を設定します。

{
  "$schema": "https://json.schemastore.org/lerna.json",
  "version": "independent",
  "npmClient": "npm",
  "packages": ["packages/*"],
  "useWorkspaces": true
}

• バージョン管理モードを選択します。
  • "version": "independent" - 各パッケージを個別にバージョン管理します。
  • "version": "1.0.0" - 固定／ロックモードで、すべてのパッケージを同じバージョンにします。
• useWorkspaces: true を設定して、ワークスペースとの連携を有効にします。

ワークスペースとの連携

ルートの package.json で npm／yarn／pnpm のワークスペースを設定します。

{
  "workspaces": ["packages/*"],
  "private": true
}

• hoisting とリンクはパッケージマネージャーに任せます。
• Lerna はバージョン管理、公開、スクリプトの実行に使用します。

タスクの実行

• パッケージ全体でスクリプトを実行します。
  • lerna run build - すべてのパッケージでビルドを実行します。
  • lerna run test --scope=@org/package - 特定のパッケージで実行します。
  • lerna run lint --since main - 変更されたパッケージのみで実行します。
• リアルタイムで出力するには --stream を使用します。
• 並行実行するには --parallel を使用します。

バージョン管理のワークフロー

• lerna version でバージョンを更新します。
  • lerna version patch - パッチバージョンを上げます。
  • lerna version minor - マイナーバージョンを上げます。
  • lerna version major - メジャーバージョンを上げます。
  • lerna version - バージョンを対話形式で選択します。
• Lerna は自動的に以下を行います。
  • package.json のバージョンを更新します。
  • 内部依存関係のバージョンを更新します。
  • git タグを作成します。
  • リモートにプッシュします。

パッケージの公開

• lerna publish で公開します。
  • lerna publish - 前回のリリース以降に変更されたパッケージを公開します。
  • lerna publish from-git - git でタグ付けされたパッケージを公開します。
  • lerna publish from-package - 未公開のバージョンがあるパッケージを公開します。
• .npmrc または lerna.json で npm レジストリを設定します。
• プレリリースバージョンには --dist-tag を使用します。

変更の検出

• 変更されたパッケージには --since フラグを使用します。
  • lerna run test --since main
  • lerna changed - 前回のタグ以降に変更されたパッケージを一覧表示します。
  • lerna diff - 前回のリリース以降の差分を表示します。
• CI では影響を受けるコマンドを活用して効率化します。

Conventional Commits

自動バージョン管理のために Conventional Commits を有効にします。

{
  "command": {
    "version": {
      "conventionalCommits": true,
      "message": "chore(release): publish"
    }
  }
}

• コミット内容によってバージョンの更新幅が決まります。
  • fix: - パッチバージョン
  • feat: - マイナーバージョン
  • BREAKING CHANGE: - メジャーバージョン
• 変更履歴を自動生成します。

依存関係の管理

• 内部パッケージ参照を使用します。

  {
    "dependencies": {
      "@org/shared-utils": "^1.0.0"
    }
  }
  

• Lerna はバージョン管理時に内部依存関係を同期します。
• ワークスペースを使って共通の依存関係をルートに hoisting します。

CI/CD との連携

• ルートで依存関係を一度だけインストールします。
• 効率的な CI のために --since を指定して lerna run を使用します。
• 適切な npm 認証を設定して、CI から公開します。
• 非対話形式で公開するには --yes フラグを使用します。

ベストプラクティス

• パッケージの目的を絞り、単一の役割にします。
• パッケージ名に一貫性を持たせます：@org/package-name
• パッケージ間の依存関係の境界を明確に保ちます。
• パッケージの API と使用方法をドキュメント化します。
• 型チェックには、プロジェクト参照を使った TypeScript を使用します。
• パッケージ単位と統合レベルの両方で適切なテストを実施します。
• 高度なキャッシュとタスク実行のために、Nx との連携を検討します。