js-sdkからの移行

このガイドでは、kintone/js-sdkのプラグイン開発ツールからcli-kintoneへ移行する方法を説明します。

概要

kintone/js-sdkは、プラグイン開発のためにいくつかのnpmパッケージを提供しています：

• @kintone/create-plugin - プラグインテンプレートの作成
• @kintone/plugin-packer - プラグインをzipファイルにパッケージ化
• @kintone/plugin-uploader - プラグインをkintoneにアップロード

cli-kintoneは、これらのツールを単一のCLIに統合しています。

なぜcli-kintoneに移行するのか

kintone/js-sdkからcli-kintoneへの移行には、以下のようなメリットがあります：

• 導入・学習コストの集約
• インターフェースと動作の改善

導入・学習コストの集約

kintone/js-sdkでは、プラグイン開発に必要な機能が複数のnpmパッケージ（@kintone/create-plugin、@kintone/plugin-packer、@kintone/plugin-uploader）に分散していました。 それぞれのパッケージを個別にインストールし、異なるコマンドとオプションを学習する必要がありました。

cli-kintoneでは、これらすべての機能を1つのCLIに統合しています。単一のツールをインストールするだけで、プラグインの作成からアップロードまでのすべての操作が可能になり、学習コストが大幅に削減されます。 また、cli-kintone pluginという統一された名前空間のもとで、一貫したコマンド構造とオプション名を採用しています。

インターフェースと動作の改善

cli-kintoneでは、kintone/js-sdkの使用経験から得られたフィードバックをもとに、以下のような改善を行っています：

• 明示的な秘密鍵生成: 秘密鍵の生成を専用のplugin keygenコマンドに分離し、鍵の生成の挙動がより明確になりました
• 一貫したオプション設計: すべてのコマンドで統一されたオプション名（--input、--outputなど）を採用し、直感的に使えるようになりました
• 追加機能: plugin infoコマンドにより、プラグイン情報を確認できるようになりました

また、一部のコマンドでは従来のjs-sdkから内部動作の改善を行なっています：

• plugin upload: kintone REST APIを利用するため、RPAで動作していた従来のplugin-uploaderに比べてアップロード時の動作が安定・高速化しています

ツールの比較

js-sdkのツール	cli-kintoneのコマンド	説明
@kintone/create-plugin	plugin init	新しいプラグインプロジェクトを初期化
@kintone/plugin-packer	plugin pack	プラグインをzipファイルにパッケージング ※秘密鍵の生成はplugin keygenコマンドに分離
@kintone/plugin-uploader	plugin upload	プラグインをkintone環境にアップロード
-	plugin keygen	プラグイン用の秘密鍵を生成
-	plugin info	プラグイン情報を表示

主な違い

コマンド構造

• js-sdk： 各ツールは独立したnpmパッケージで、それぞれ独自のコマンドを持ちます
• cli-kintone： すべてのプラグインコマンドはcli-kintone plugin名前空間の下にあります

オプション名

一部のオプション名がツール間で異なります：

機能	js-sdk	cli-kintone
入力ディレクトリ/ファイル	位置引数	--input, -i
出力ファイル	--out	--output, -o
秘密鍵ファイル	--ppk	--private-key

詳細なインターフェース差分については、コマンドごとのインターフェース差分および主な違いを参照してください。

移行手順

1. cli-kintoneのインストール

まず、cli-kintoneをグローバルまたはプロジェクト内にインストールします。詳細はインストールを参照してください。

npm install @kintone/cli --global

2. 手順の更新

新しいプラグインの作成

移行前（js-sdk）：

kintone-create-plugin my-plugin --template javascript

移行後（cli-kintone）：

cli-kintone plugin init --name my-plugin --template javascript

秘密鍵の生成

js-sdkのcreate-pluginでは、秘密鍵は最初のビルド時に自動的に生成されます。cli-kintoneでは、明示的に生成します：

cli-kintone plugin keygen --output private.ppk

プラグインのパッケージ化

移行前（js-sdk）：

kintone-plugin-packer --ppk private.ppk --out plugin.zip ./src/

移行後（cli-kintone）：

cli-kintone plugin pack --input ./src/manifest.json --output ./plugin.zip --private-key ./private.ppk

監視モード：

cli-kintone plugin pack --input ./src/manifest.json --output ./plugin.zip --private-key ./private.ppk --watch

プラグインのアップロード

移行前（js-sdk）：

kintone-plugin-uploader --base-url https://example.cybozu.com --username admin --password password plugin.zip

移行後（cli-kintone）：

cli-kintone plugin upload --input ./plugin.zip --base-url https://example.cybozu.com --username admin --password password

監視モード：

cli-kintone plugin upload --input ./plugin.zip --base-url https://example.cybozu.com --username admin --password password --watch

プラグイン情報の表示

cli-kintoneは、プラグイン情報を表示する追加のコマンドを提供します：

cli-kintone plugin info --input ./plugin.zip --format json

3. package.jsonスクリプトの更新

js-sdkツールを使用しているnpmスクリプトがある場合は、cli-kintoneを使用するように更新してください：

移行前（js-sdk）：

{
  "scripts": {
    "start": "kintone-plugin-packer --ppk private.ppk --watch src/",
    "build": "kintone-plugin-packer --ppk private.ppk src/",
    "upload": "kintone-plugin-uploader --base-url https://example.cybozu.com --username admin --password password plugin.zip"
  }
}

移行後（cli-kintone）：

{
  "scripts": {
    "start": "cli-kintone plugin pack --input ./src/manifest.json --private-key ./private.ppk --watch",
    "build": "cli-kintone plugin pack --input ./src/manifest.json --private-key ./private.ppk",
    "upload": "cli-kintone plugin upload --input ./plugin.zip --base-url https://example.cybozu.com --username admin --password password"
  }
}

4. js-sdkツールのアンインストール（任意）

cli-kintoneへの移行が完了したら、js-sdkツールを削除できます：

npm uninstall @kintone/create-plugin @kintone/plugin-packer @kintone/plugin-uploader

コマンドごとのインターフェース・挙動差分

plugin init (@kintone/create-plugin との比較)

オプション	js-sdk	cli-kintone	備考
プラグイン名	コマンドライン引数で入力	--name <name> オプションまたは対話形式で入力	デフォルト値はkintone-plugin
テンプレート	minimum または modernが選択可能 デフォルト値はminimum	javascript または typescriptが選択可能 デフォルト値はjavascript
plugin-uploaderのインストール	インストールするかどうかを対話形式で確認 デフォルト値はNo (インストールしない)	デフォルトでcli-kintoneをインストールします。開発用スクリプトではplugin uploadコマンドを利用するように設定されます
--langオプション	コマンド実行中の表示言語を指定できます	--langオプションは廃止され、英語での表示のみになりました

実行例：

# js-sdk（対話形式）
kintone-create-plugin my-plugin --template minimum

# cli-kintone（非対話モード）
cli-kintone plugin init --name my-plugin --template javascript

plugin pack (@kintone/plugin-packer との比較)

オプション	js-sdk	cli-kintone	備考
入力ソース	コマンドライン引数	--input <dir>, -i	js-sdkではmanifest.jsonの存在するディレクトリを指定していました cli-kintoneではmanifest.json自体のパスを指定します。
出力ファイル	--out <file>	--output <file>, -o	デフォルトはplugin.zip
秘密鍵	--ppk <file>	--private-key <file>, -p	js-sdkでは未指定時は自動生成していました。 cli-kintoneでは自動生成せず、事前にplugin keygenコマンドで生成してもらう必要があります。

実行例：

# js-sdk
kintone-plugin-packer --ppk private.ppk --out plugin.zip src/

# cli-kintone
cli-kintone plugin pack --input ./src/manifest.json --output ./plugin.zip --private-key ./private.ppk

plugin upload (@kintone/plugin-uploader との比較)

オプション	js-sdk	cli-kintone	備考
入力ファイル	コマンドライン引数	--input <file>, -i
確認プロンプト	なし	アップロード直前に操作（追加・更新）の確認プロンプトが表示されます。プロンプト表示せずに実行するには--yesオプションを指定してください。

実行例：

# js-sdk
kintone-plugin-uploader --base-url https://example.cybozu.com --username admin --password password plugin.zip

# cli-kintone（パスワード認証）
cli-kintone plugin upload --input ./plugin.zip --base-url https://example.cybozu.com --username admin --password password

お困りの場合

移行中に問題が発生した場合：

• プラグインコマンドのドキュメントを確認してください
• トラブルシューティングガイドを確認してください
• GitHub Issuesで問題を報告してください

参考資料

• @kintone/plugin-packer - npm
• @kintone/plugin-uploader - npm
• @kintone/create-plugin - npm
• kintone/js-sdk GitHubリポジトリ