CLI プラグインの開発

最終更新日 2024年05月09日(木)

プラグインの作成
プラグインのインストール
Heroku API の使用
デバッグ時のヒント
プラグインのリリース

Heroku CLI は、プラグイン機能を持つ oclif に基づいています。ユーザーは、heroku plugins:install PLUGINNAME を使用してプラグインをインストールします。ここで、PLUGINNAME は npmjs.com 上の npm パッケージです。プラグイン開発者は、下記のように、heroku plugins:link を使用してそれらのプラグインを CLI にリンクすることもできます。

Heroku CLI についての詳細は、GitHub 上のプロジェクトを確認してください。

プラグインは、マシンにインストールされているノード (存在する場合) のバージョンには関係なく、ノードの現在のバージョン (通常は最新) で動作します。ノードの古いバージョンをサポートする必要はありません。

ここでは、単純な hello world プラグインの開発について説明します。より完全な例については、heroku-git プラグインを確認してください。

プラグインの作成

oclif を使用して新しいプラグインを生成します (npx は npm に付属しており、oclif を自動的にインストールする)。

$ npx oclif generate myplugin

プラグインのインストール

npmjs.com 上のプラグインは heroku plugins:install を使用してインストールできますが、プラグインをローカルで開発している場合は heroku plugins:link を使用する必要があります。これにより、プラグインが検証され、~/.local/share/heroku/plugins/linked.json でリンクされます。

このプラグインをローカルで設定するには、プラグインディレクトリのルートに移動してプラグインをリンクします。

$ cd myplugin
$ heroku plugins:link
$ heroku hello world
hello world! (./src/commands/hello.ts)

Heroku API の使用

CLI の内部では oclif コマンドが正常に動作しますが、Heroku API を使用する場合は、Heroku CLI コマンドの基本クラスを使用する必要があります。

最初に、yarn add @heroku-cli/command を使用してプロジェクトに基本クラスを、さらに yarn add -D @heroku-cli/schema を使用して API スキーマタイプを追加します。その後、次のようにコマンドを編集します。

// note that we are using @heroku-cli/command instead of @oclif/command
// this inherits from @oclif/command but extends it with Heroku-specific functionality
import {Command, flags} from '@heroku-cli/command'
import * as Heroku from '@heroku-cli/schema'

export default class AppCommand extends Command {
  static description = 'say hi to an app'
  static flags = {
    remote: flags.remote(),
    app: flags.app({required: true})
  }

  async run () {
    const {flags} = await this.parse(AppCommand)
    const response = await this.heroku.get<Heroku.App>(`/apps/${flags.app}`)
    const app = response.body
    console.dir(app)
  }
}

使用可能なコマンドオプションについての詳細は、oclif のドキュメントを参照してください。

デバッグ時のヒント

オブジェクトをプリティプリントするには、console.dir() を使用します。

デバッグステートメントを出力するには、HEROKU_DEBUG=1 を使用してコマンドを実行します。ヘッダーも取得するには HEROKU_DEBUG_HEADERS=1 とします。多くの内部デバッグ出力を得るには、DEBUG=* を使用します。

追加のエラー出力を得るには、~/Library/Caches/heroku/error.log を検査します。

プラグインのリリース

heroku plugins:install を実行してプラグインをインストールするには、そのプラグインを npmjs.com で公開することのみが必要です。

アカウントを作成し、ターミナルからそのアカウントにログインします。

$ npm login
Username: jdxcode
Password:
Email: (this IS public) npm@heroku.com
Logged in as jdxcode on https://registry.npmjs.org/

npm への公開を簡単にするために np を使用することをお勧めします。次を使用して更新をリリースできます。

$ npx np

これにより、新しいバージョンの入力が求められ、テストが実行され、さらに適切なリリースが実行されていることを確認するためのその他のチェックが実行されます。

リリースチャネル

プラグインにベータ、ステージング、または開発チャネルを割り当てるには、npm dist-tag を使用できます。

最初に、パッケージを dist-tag に公開します。

npm publish --tag beta

次に、そのタグを使用してプラグインをインストールします。

heroku plugins:install myplugin@beta

CLI は引き続き、ベータチャネルでプラグインを任意の新しいリリースに更新します。

Categories