前置き
2019 年 10 月末にリリースされました kintone CLI。
記事執筆時点（2020 年 6 月中旬）の時点ではバージョン 0.1.4 と正式リリースまではまだまだ遠そうな β 版で、しかも 3 ヶ月くらいバージョンアップが止まっていると言う若干死臭が漂いつつある感じがしますが、とは言えこれはかなりできるやつです。
ただ、いい感じに使うにはいい感じに準備や設定をしてあげなければいけない感じもあり、この記事ではその辺りを解説していきたいと思います。
kintone CLI の立ち位置
kintone CLI は、役割としては Create React App とか Vue CLI の kintone 版と考えれば良いでしょう。
このツールでは
- 対話式でプロジェクトを初期化
- ローカルサーバーでのリアルタイムプレビュー
- コマンドでカスタマイズをビルド＆デプロイ
と言った事が行えます。
よく似た名前の cli-kintone とは全く関係なく、依存関係もありません。
（あちらは kintone をコマンドラインで操作するためのクライアントツール。psql とか mysql などと同じ立ち位置です。）
準備
kintone CLI(β) のインストール
公式 の手順に従い、インストールを実施します。
npm install -g git://github.com/kintone/kintone-cli.git
カスタマイズを適用するアプリを準備する
kintone CLI では、通常のアプリのカスタマイズ開発、あるいはプラグイン開発のいずれかのテンプレートを選択することになります。
今回は kintone 開発の大部分を占めるであろうアプリ向けカスタマイズを例に取り上げます。
カスタマイズを適用するアプリは（道中でアプリ ID の入力を求められるため）事前に準備しておくのがスムーズです。
kintone CLI を使う
プロジェクトを初期化する
アプリの準備ができたら、まずはプロジェクトを作ります。
ターミナルでプロジェクトを作成しようとするフォルダに移動しておいて、以下のように実行します。
kintone-cli init
対話式でいろいろ訊かれて来ます。
ここで入力したものは package.json に反映されます。
Project name
プロジェクト名を決めて入力します。
特段入力制限はないようですが、慣例的にスネークケースで書いとけばいいんじゃないでしょうか。
Version
バージョン番号です。
Descirption
プロジェクトの詳細を入力します。
Author
プロジェクトの作者。
License
ライセンスの種類。
Do you want to use @kintone/kintone-ui-component?
kintone UI Component を利用するかどうか。
kintone の標準 UI ぽいアピアランスのコンポーネントがいろいろ用意されています。
Do you want to use @kintone/kintone-js-sdk?
kintone JS SDK を使用するかどうか。
同 SDK は既に deprecated です。
kintone の SDK は @kintone/rest-api-client が現在の最新ですから、ここは no にして後から @kintone/rest-api-client を手動で追加すれば良いでしょう。
と言うか kintone CLI 自身がこの辺りちゃんと追随してくれてれば良いのに。と思いますが。
なお@kintone/rest-api-client についてはこちらにざっくりと記載しています。
今回は以下のような感じで実行しました。
プロジェクトを作成する
ここまでの手順で行われたのは、
- プロジェクトを格納するフォルダを作成
- その中に
package.jsonファイルを作成 - git リポジトリの初期化
だけです。
実際にプロジェクトを作成するには、上のスクショでも示されている通り
kintone-cli create-template
を実行してくださいね。と促されます。
ところが、これが実は罠。
このまま続けて kintone-cli create-template を実行すると対話プロンプト自体は開始しますが、最後に無情にも package.json not found. と突っぱねられてしまいます。
つまり、先のコマンドで作成されたフォルダ（package.jsonがあるフォルダ）に移動してから kintone-cli create-template しなきゃならないと言うトラップがありますので注意です。
実際のところは、作成されたフォルダを VS Code で開き、ターミナルを開いて実行するのがスムーズだと思います。
で、その対話式でいろいろ訊かれる内容ですが、また 1 つ 1 つ見ていきましょう。
What type of app you want to create ?
アプリ向けのカスタマイズ開発か、プラグイン開発かの選択です。
Do you want to set authentication credentials ?
認証情報をセットするかどうか。詳しくは後述します。
What is your kintone domain ?
カスタマイズを適用する先の kintone ドメインの指定。
What is your kintone username ?
当該環境にログインするためのユーザー名。
What is your kintone password ?
そのパスワード。入力はマスクされます。
Do you use proxy ?
接続にプロキシを使うかどうか。よしなに。
Do you want to use React ?
開発フレームワークとして React を使うかどうか。
執筆時点では Vue.js などは使えません。もちろん自前でセットアップすれば使えますが。
Do you want to use TypeScript ?
TypeScript を使用するかどうか。
Do you want to use webpack ?
バンドラーとして Webpack を使うかどうか。No にする理由はあまり思い当たらない。
What is the entry for webpack ?
Webpack を使用する際のエントリポイントとなるファイル。
What is the app name ?
これは結構重要です。
プロジェクトはここで指定された名前でディレクトリが切られ、ソースやら各種設定やら一式はその下に格納されます。
Create React App や Vue CLI がプロジェクト直下にそれらのファイルを作成するのとは対照的です。
無駄に階層が深くなるだけのような気がしますが、そういう設計思想みたいです。
そしてここで付けた名前が、ローカルプレビュー時やビルド・デプロイ時にも必要になって来ます。
ここは、「app」みたいなシンプルな名前にしておくのが良いと思います。
Do you want to use @cybozu/eslint-config for syntax checking ?
サイボウズ謹製の eslint 設定を利用するかどうか。
What is the app ID ?
カスタマイズを適用するアプリの アプリ ID を入力します。
ここでこの値を入力するため、事前にアプリを作っておく必要があるのです。
（適当な値を入れておいて、あとから設定ファイルを直接手で直してもいいのですが）
What is the scope of customization ?
カスタマイズをアプリの利用者全員に適用するか、管理者だけにするか、適用しないか。
kintone アプリの設定の「JavaScript / CSS でカスタマイズ」の「適用範囲」のラジオボタンに対応する項目ですね。
今回は以下のような感じで実行しました。
この時点で以下のようなディレクトリ・ファイル構成となります。
この中で特に気を払って欲しいのが app/auth.json ファイルです。
このファイルには認証情報が平文で記録されます。
従ってこのファイルは 絶対にリポジトリに追加してはいけません。
もっとも、.gitignore ファイルにはきちんとこの app/auth.json ファイルを無視するようはじめから設定されています。
まかり間違ってこの記述を無効にしてしまわないよう十分に気をつけましょう。
「うちはソース管理は SVN なんだ」みたいな現場では .gitignore も効果をなさないわけで、この場合はものすごく注意が必要です。
app/config.json には、道中で設定したアプリIDやカスタマイズの適用先などの情報が含まれています。
自動作成されたものを後から修正する事はあまりないでしょうが、念のため内容を確認しておくと良いかと思います。
開発する
kintone-cli dev --app-name app --watch --localhost
と実行することで、ローカルサーバが立ち上がり、開発ビルドが走り、指定したアプリにカスタマイズが適用されます。
（app の部分は先ほどの What is the app name ? で答えたもの）
アプリのカスタマイズ設定には以下のように反映されます。
アプリの実際の画面にも反映されています。
ソースファイルに修正を加えれば、それを検知して自動ビルドがかかり、画面上にもすぐに反映されます。
とっても便利！
この際、他のカスタマイズが適用されていたら全て消えてしまいますので、この点は充分注意してください。
ビルド＆デプロイする
とは言え、現時点ではローカルのファイルを参照しているだけであり、実運用には適しません。
ビルドし、デプロイするのは以下のようにします。
kintone-cli build --app-name app
kintone-cli deploy --app-name app
アプリ側にはちゃんとビルドされたファイルが適用されます。
いちいち手動でファイルを適用してアプリの変更を保存する手間が省けます！
とっても便利！
kintone CLI の至らないところをどうにかする
と言った具合に、非常に使い勝手が良いのでもっと向上して欲しいしもっと流行って欲しいkintone CLIですが、さすが β 版と言ったところか、現時点ではいくつかの問題があります。
ただしこれらはある程度処置をすれば回避可能ですので、以下に微妙な点の内容と回避方法を解説します。
またこれらの問題は kintone CLI のバージョンアップに伴い改善される可能性があります。
デフォルトポート 8000 問題
開発サーバを立ち上げると自動的にポート 8000 番で起動しようとします。
ポート 8000 番・・・だいたい何かしらで埋まってますよね。
違うポートを使いたい場合は、package.json の scripts の dev を以下のように、
"scripts": {
"dev": "ws --port 8081",
(省略)
}
ws のあとに --port (任意のポート番号) とすれば OK です。
kintone CLI コマンド長すぎ問題
README を読む限り、kintone CLI には dev、build、deploy、lint などのサブコマンドがあります。
そして、例えば dev であれば、
kintone-cli dev [--app-name <App Name>] [--watch] [--localhost]
と記述されており、--app-name <App Name> パラメータは省略可能であるかのように読み取れます。
しかしこれが罠。
無情！！！ アプリ名を付けないと怒られます。
従って、最低限
kintone-cli dev --app-name <App Name>
までは入力しなければ実行できません。
こんなのいちいち打ってられるか！！
第一 <App Name> は最初（create-template の時）に決めた名前で確定しているのだから、いちいち入力するのは非効率！！
と言う事で、こんな感じで package.json の script に入れてしまうのが良いでしょう。
"scripts": {
"devel": "kintone-cli dev --app-name app --watch --localhost",
"build": "kintone-cli build --app-name app",
"deploy": "kintone-cli deploy --app-name app",
"dev": "ws --port 8081",
"build-app": "webpack --config app/webpack.config.js",
"lint-all": "eslint . --ext .js,.jsx,.ts,.tsx",
"lint-all-fix": "eslint . --ext .js,.jsx,.ts,.tsx --fix",
"lint-app": "eslint app/ --ext .tsx",
"lint-app-fix": "eslint app/ --ext .tsx --fix"
}
いちばん上の devel から 3 つめの deploy までの行を追加しています。
こうしておけば npm run devel とやるだけで開発サーバをウォッチ状態で実行できるようになるわけです。
kintone オブジェクトのコード補完利かない問題
これ自体は kintone CLI 固有の問題と言うわけではありませんが。
デフォルトでは kintone オブジェクトは app/source/global.d.tsx ファイルで以下のように定義されています。
declare let kintone: any;
any 型として定義されてしまっていますので、当然ながらコード補完は利かず、なんとも歯がゆい感じが拭えません。
これは、kintone-extension を使えば解決できます。
VS Code を使って kintone 開発をしている人は正味な話マストってぐらいだと思うのですが、なぜか流行っていません。
こちらの記事でも紹介していますので、入れておくのが良いでしょう。
それと、TypeScript で開発を進めて行くならいずれにしろ必要になるので、@kintone/dts-gen もインストールして設定をしておきましょう。
こちらの記事で解説しています。
他のカスタマイズが消えてしまう問題
上述した通り、アプリに対して別にカスタマイズを適用していた場合でも、kintone-cli dev や kintone-cli deploy に伴い、その設定は失われてしまいます。
（厳密には今回のカスタマイズで上書きされる動き）
例えば、複数の作業者が 1 つのアプリに対して個別にカスタマイズを開発しているなどと言うシチュエーションでは受容できないレベルの問題となるでしょう。
これに関しては、今のところ回避の術や次善策はありません。
既存のカスタマイズと併用したい場合は、そのカスタマイズスクリプトをこちらのプロジェクトに組み込むなどして対応するより他ないかなと思います。
この辺はなんとかなって欲しいかなと思いますけれども、難しそうだなとも思います。
ソースの階層が 1 段低い問題
kintone-cli create-template は 1 つのプロジェクトで何度も実行することができ、その都度サブディレクトリが作られることから、このツールが設計思想として 1 つのプロジェクトに複数のアプリに対するカスタマイズを内包すると据えているものと考えられます。
実際のカスタマイズの現場では 1 つのアプリに対する開発だけで済むことはあまりなく、多くは複数のアプリの組み合わせで 1 つの業務システムを構築するわけですから、そう言う意味ではそれを大きく 1 つのプロジェクトとして取り扱う思想は妥当性があります。
この記事ではアプリ名は app などシンプルな名前にするのが良いと言及しましたが、複数アプリに対するカスタマイズを開発するのであれば、シンプルかつ区別がつきやすい命名規則を考える必要があるでしょう。
ただまあ、1 つのプロジェクトでいくつものアプリのカスタマイズを抱えると言う事になると、その分 package.jsonのscriptsがどんどん複雑になって来ると言う事にもなりますが。
React じゃなく Vue.js 使えないんです？
現時点では使えないんですねえ・・・。
自前で Vue.js をプロジェクトに組み込んでやる必要がありそうですが、なかなか容易ではない感じがします。
理想としては Vue CLI で作ったプロジェクトに対して kintone CLI で開発・ビルド・デプロイができるようになれば結構に最強だと思うのですが。
このあたりは個人的にも調査を進めているところで、いい結果が得られたら記事にしたいと思っています。
2020/06/23 追記
Vue CLI と kintone CLI を（無理っくり）共存させる構成ができました。
以下で解説しています。
とは言え、やっぱり公式にサポートしてもらうのがいちばん良い。
（kintone-cli create-template の流れで Vue.js が選択できるようになれば良い）
しかしながら、そもそも kintone UI Component 自体が React 版しかないので、kintone CLI で Vue.js を公式サポートしてくれるようになるのは正直かなり可能性が低かろうなと思っています。
まとめ
ここまで見て来た通り、ローカルサーバでカスタマイズのテストができる、コマンド一発でビルド・デプロイできると言う点だけをとってみても kintone CLI は大変に有用で、これだけでも使う価値がある。
UI ガッツリカスタマイズします系案件なら kintone UI Component も使えますし。
ただ、開発が滞っている雰囲気がすごい事、ディレクトリ構成が独特で他のいろんなツール類との調整が大変そうなところなど若干採用に二の足を踏むところがあるのも事実。
まずは単一アプリの比較的小規模なカスタマイズから利用していくと言うのが程よいラインかも知れません。
と言うことで、 kintone CLI のざっくりレビューでした！
どちら様も良き kintone ライフを！