Zenn
Closed14

rush コマンド

TypeScript
monorepo
rush
rushstack
K.InabaK.Inaba

開発者向けチュートリアルから

https://rushjs.io/pages/developer/new_developer/

npm install -g @microsoft/rush

npm でグローバルインストールして使う

以降、該当の Git リポジトリ配下の NPM パッケージはすべて rush コマンドでするので、パッケージ管理系のコマンド ( npm, yarn, pnpm ) を叩かないように注意。
叩くにしても rush unlink で管理を一旦切ってから、らしい。

K.InabaK.Inaba

よく使うコマンドのページ

https://rushjs.io/pages/developer/everyday_commands/

  • rush update
    common/config, package.json の操作後や、git pull の実行後等に、node_module の依存関係を解決してパッケージをインストールする

  • rush rebuild
    リポジトリ内のビルドタスクを全部走らす

  • rush build
    リポジトリ内のうち、変更があったプロジェクトのみビルドタスクを走らせる
    ただし、使用しているツールチェーンがインクリメンタルビルドに対応している場合

  • rushx
    プロジェクトのディレクトリ配下で、NPM スクリプトを走らせる
    つまり npm run 相当

  • rush check
    リポジトリ内の複数プロジェクトにまたがって、同一のパッケージの異なるバージョンに依存していないか確認する
    CI ビルドのステップに組み込むと、依存がキレイに保たれていない時 Fail してくれてうれしい

  • rush change
    プロジェクトの変更を Git にコミットしたあとにこのコマンドを実行すると、common/changes 以下にいい感じに change log を吐いてくれるらしい？
    リリースする時、上の change log をまとめて CHANGELOG.md を吐いてくれるらしい？
    あとで別ページの解説を触る https://rushjs.io/pages/best_practices/change_logs/

K.InabaK.Inaba

以降、該当の Git リポジトリ配下の NPM パッケージはすべて rush コマンドでするので、パッケージ管理系のコマンド ( npm, yarn, pnpm ) を叩かないように注意。

じゃあどうやって NPM パッケージインストールすんねん、へのアンサー。
https://rushjs.io/pages/developer/modifying_package_json/

# DON'T DO THIS IN A RUSH REPO:
~/my-repo$ cd apps/my-app
~/my-repo/apps/my-app$ npm install --save example-lib

という改めて強い注意喚起から始まる

代わりに

rush add --package example-lib

で package.json を編集しつつパッケージのインストールが行われる。

@ で具体的なバージョンを指定したり、
チルダ ~ やキャレット ^ での依存解決の条件付けもできる。

rush update --full で依存を解決して最新のパッケージにアップデート。
具体的なバージョンの範囲を指定したアップデートは rush のコマンドでは現在提供されていない。
外部ツールと組み合わせた解決策はある。

K.InabaK.Inaba

以上、開発者向けチュートリアルのうち最低限抜粋。
以下、リポジトリメンテナ向けチュートリアル。

K.InabaK.Inaba

新しいリポジトリを開始するとか、リポジトリにプロジェクトを引っ越してくるとか。
https://rushjs.io/pages/maintainer/setup_new_repo/
https://rushjs.io/pages/maintainer/add_to_repo/

rush init で一連の管理ファイルを生成してくれる。
あとはパッケージ ( ≒ プロジェクト ) のフォルダを足して、rush.json ファイルの projects 以下に足して

rush.json
  "projects": [
    {
      "packageName": "some-package",
      "projectFolder": "packages/some-package"
    }
  ]

rush の管理下で使い始めることができる

K.InabaK.Inaba

CI ツールで自動ビルドを組んでいる場合、rush コマンドの導入するプラクティス。
https://rushjs.io/pages/maintainer/enabling_ci_builds/

リポジトリに rush init で生成した common ディレクトリには、rush.json ファイルを読み出して、rushVersion の項目に記された特定のバージョンの rush を実行できる CI 環境を構築してくれる install-run-rush.js スクリプトが組み込まれている。

このスクリプトは、環境構築が済んでいる場合は rush コマンドのエイリアスのように振る舞う。

つまり、CI 環境の定義ファイルでは rush コマンドの代わりにこのスクリプトを呼ぶことになる。

# installing rush command + run "rush install"
node common/scripts/install-run-rush.js install

# run "rush rebuild --verbose"
node common/scripts/install-run-rush.js rebuild --verbose

rush init で Travis CI 向けの設定ファイルがデフォルトで生成されたり、Azure との相性を考えたプラクティスだったりで、GitHub Actions に組み込みたい目線だとどこまで使えるかは要検証。

K.InabaK.Inaba

やっといたほうが良い設定項目
https://rushjs.io/pages/maintainer/recommended_settings/

  • repository.url
    rush change を利用して change log を吐いている場合に推奨。
    ベースブランチとの差分を正確に取ってくれるようになる、とのこと。
rush.json
  "repository": {
    // Replace this with the URL that you use when running "git clone" for your repo
    "url": "https://github.com/microsoft/rush-example"
  }

  • ensureConsistentVersions
    true にすると、以下のコマンド実行時、同時に裏で rush check コマンドを走らせてくれる。

    • rush install
    • rush update
    • rush link
    • rush version
    • rush publish

  • strictPeerDependencies
    厳密な依存解決を有効にする PNPM のオプション --strict-peer-dependencies を利用する。

K.InabaK.Inaba

以上、リポジトリメンテナ向けチュートリアルのうち最低限抜粋。
NPM パッケージとしてのリリース、デプロイは既存の GitHub Actions フローとどこまで統合できるかやってみないとわからないので未着手。

K.InabaK.Inaba

ワークロードに Rush を取り込んでから大体 1 年間新規開発タスクをこなしてきて、既存パッケージのメンテはどうやるんだ？を調べる段階になったので再開。

K.InabaK.Inaba

まず、

Q. rush コマンド自体のアップデートがリリースされているのですが、どうアップデートしたらいいですか？

A. プラグインを使うといいよ

https://rushjs.io/pages/maintainer/using_rush_plugins/
https://github.com/bytesfriends/rush-plugins/tree/main/rush-plugins/rush-upgrade-self-plugin

もともと Rush で管理するリポジトリは、ルートの rush.json ファイルで rushVersion や pnpmVersion 等の管理をしていて、コントリビューターはこの指定に従ってオペレーションを行う必要がある。
この共通設定ファイルを操作する手間など、微妙に面倒な作業を自動化するための plugin 機能が提供されている。

rush init-autoinstaller --name rush-plugins
common/autoinstallers/rush-plugins/package.json
{
  "name": "rush-plugins",
  "version": "1.0.0",
  "private": true,
  "dependencies": {
    // 任意のインストールしたいプラグインパッケージ
    "rush-upgrade-self-plugin": "^1.0.7"
  }
}

rush update-autoinstaller --name rush-plugins
common/config/rush/rush-plugins.json
{
  "$schema": "https://developer.microsoft.com/json-schemas/rush/v5/rush-plugins.schema.json",
  "plugins": [
    /**
     * Each item defines a plugin to be loaded by Rush.
     */
    {
      /**
       * The name of the NPM package that provides the plugin.
       */
      "packageName": "rush-upgrade-self-plugin",

      /**
       * The name of the plugin.  This can be found in the "pluginName"
       * field of the "rush-plugin-manifest.json" file in the NPM package folder.
       */
      "pluginName": "rush-upgrade-self-plugin",

      /**
       * The name of a Rush autoinstaller that will be used for installation, which
       * can be created using "rush init-autoinstaller".  Add the plugin's NPM package
       * to the package.json "dependencies" of your autoinstaller, then run
       * "rush update-autoinstaller".
       */
      "autoinstallerName": "rush-plugins"
    }
  ]
}

依存パッケージの解決をすれば

rush update

rush-upgrade-self-plugin の導入が完了している。
使ってみる

❯ rush upgrade-self


Rush Multi-Project Build Tool 5.68.2 - https://rushjs.io
Node.js version is 16.19.1 (LTS)


Trying to acquire lock for pnpm-6.7.1
Acquired lock for pnpm-6.7.1
Found pnpm version 6.7.1 in /home/kinaba/.rush/node-v16.19.1/pnpm-6.7.1

Symlinking "/home/kinaba/git/projectRoot/common/temp/pnpm-local"
  --> "/home/kinaba/.rush/node-v16.19.1/pnpm-6.7.1"
Acquiring lock for "common/autoinstallers/rush-plugins" folder...
Autoinstaller folder is already up to date

Starting "rush upgrade-self"

? Pick up a target version (Use arrow keys)
❯ 5.96.0 
  5.95.0 
  5.94.1 
  5.94.0 
  5.93.1-pr3481.17 
  5.93.2 
  5.90.2-pr3964.0

対話型でアップデートができる

K.InabaK.Inaba

Q. rush 内部のパッケージ管理ツール pnpm のアップデートがリリースされているのですが、どうアップデートしたらいいですか？

A. rush.json ファイルの pnpmVersion を書き換えて rush update

rush.json
{
  "$schema": "https://developer.microsoft.com/json-schemas/rush/v5/rush.schema.json",
  "rushVersion": "5.96.0",
-  "pnpmVersion": "6.7.1",
+  "pnpmVersion": "7.30.3",
K.InabaK.Inaba

本題。

Q. 各パッケージの package.json で、古くなった dependency パッケージはどのようにアップデートしたらいいですか？

A. 対話型の個別アップデート、および全件列挙用の管理コマンドが追加されています。

https://rushjs.io/pages/developer/modifying_package_json/

rush upgrade-interactive / rush-pnpm outdated コマンドが便利～

このスクラップは2023/04/06にクローズされました