使い方

ここでの Lerna は Yarn に依存します。事前にyarnコマンドが使えるようにしておきます。

package.json を編集

package.jsonworkspacesセクションを追加します。ここに羅列したパスにマッチするディレクトリがそれぞれ実際のプロジェクト(パッケージ)というような意味になります。マッチすると言ったようにここではglobで指定するようなパスが使えます。

以下は、examplepackages/**をワークスペースに登録しています。packages/**というのはpackages/foopacakges/hoge/fugaみたいなディレクトリのことです。

あとworkspacesを設定した時は、private:trueにしないといけないのでこれも設定します。

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

Lerna の設定ファイルを作る

Lerna の設定ファイルはlerna.jsonとしてプロジェクトルートに置きます。以下は Yarn と一緒に使う場合の設定の例です。

{
  "version": "independent",
  "npmClient": "yarn",
  "useWorkspaces": true
}

version

これは各ワークスペースのパッケージのバージョンをどうするかを設定します。例えばここに、1.0.0と書くとlerna publish時にワークスペースの公開できるパッケージすべてが1.0.0で npm などに公開されます。そしてこれは、 Lerna が自動でインクリメントしてくれるので自分で編集する必要はありません。
上記のようにindependentと書くと各パッケージは独立したバージョンを持つようになります。lerna publish時、各パッケージは自身に変更があったかを確認し、変更があった場合のに公開の対象になります。バージョンは、その時にパッケージ毎に自分で設定できます。

npmClient

npmyarnなど実際に依存したいツールを指定します。

useWorkspaces

npmClient:yarnの時に、 Yarn の上記で設定したようなworkspacesをそのまま使うかを設定します。使ったほうが楽なので、tureでいいと思います。

もし、npmを使っていたり何かしら自分でワークスペースを設定したい場合はlerna.jsonpackagesというセクションを追加します。この中身はpackage.jsonに追加するworkspacesと同じ形です。

{
  "version": "independent",
  "packages": [
    "example"
    "packages/**",
  ]
}

ワークスペース一覧を表示

lsまたはlistコマンドで表示できます。これはlerna.json、または(yarnを使っている場合の)package.jsonに書かれているworkspacesで今どれがワークスペースとして認識されてるか確認できます。

lerna ls
# lerna notice cli v3.13.0
# lerna info versioning independent
# foo
# bar
# baz
# lerna success found 3 packages
# ✨  Done in 0.98s.

ここで表示されている名前はpackage.jsonnameキーの値(=パッケージ名)です。

ワークスペースの run-scripts を実行

runコマンドを使います。

run <script>ですべてのワークスペースでその<script>を実行します。例えば、 A ,B ,C というワークスペースがあり、ぞれぞれのpackage.jsonが以下のように設定されているとします。

{
  "scripts": {
    "build": "..."
  }
}

このときlerna run buildとすると、それぞれのbuild部分が実行されます。

絞り込んで実行

Lerna の--scopeフラグを使います。例えば B ワークスペースだけのbuildを実行したい場合は、以下のように実行します。

lerna run build --scope B

各ワークスペースに依存をインストール

lerna addコマンドを使います。

すべてのワークスペースに

単に後ろにパッケージ名を置くと、すべてのワークスペースにそのパッケージをインストールします。

# すべてのワークスペースに`lodash`をインストール
lerna add lodash

-Dオプションを付けるとdevDependneciesに追加です。

# すべてのワークスペースに`eslint`をインストール
lerna add -D eslint

限ったワークペースに

--scope <workspace-name>オプションを使います。

# `foo`ワークスペースに`lodash`をインストール
lerna add lodash --scope foo
# `foo`と`bar`ワークスペースに`lodash`をインストール
lerna add lodash --scope foo --scope bar

あるワークスペースパッケージを別のワークスペースパッケージにインストール

パッケージ名にワークスペースパッケージを置くと、それを依存に追加できます。例えば、foobarに依存しているなら、

lerna add foo --scope bar

とすることでfoodependenciesbarを追加できます。ワークスペース間の依存関係をちゃんとしておくこともlerna publishする時に重要になるので忘れずにlerna addしておくと良いと思います。

強制的に Publish 処理を行わせる

公開するためのコマンドはlerna publishですが、これは依存のライブラリファイルに変更が無ければ公開処理は行われません。

ただ稀に CircleCI などの公開後の設定が間違っていたりした時、そちらの設定を修正後にもう一度公開処理をさせたい場合があります。

そんな時は--force-publishオプションを付けます。

yarn lerna publish --force-publish
yarn lerna publish patch --force-publish # 最後の桁を上げて公開

といった感じです。

Lerna の為の JSON Schema

作りました。

スキーマはunpkg.com/@nju33/json-schema/schemas/lerna/lerna.jsonに置いてあります。(設定時は先に先の URL を使う必要があるので注意です)

VSCode の設定

コマンドパレットへ>Preferences: Open Settings (JSON)と入力し設定ファイルを開きます。そして中でjson.schemasへ以下のような設定をします。

{
  "json.schemas": [
    {
      "fileMatch": ["lerna.json"],
      "url": "https://unpkg.com/@nju33/json-schema@0.0.20/schemas/lerna/lerna.json"
    },
  ]
}

設定はこれだけです。

あとは適当にプロジェクトにlerna.jsonファイルを作ればチェックが効くはずです。

エラー

lerna publish 時

EUNCOMMIT

git statusなどで差分がある状態。差分をコミットするか捨てれば直ります。

lerna run 時

TypeError: Cannot read property 'split' of undefined

ルートディレクトリをワークスペースと設定している時起きました。