TypeScript による kintone プラグイン開発

この記事は kintone Advent Calender 2019 の8日目です。

Advent Calendar 初参加、kintone 関連では Qiita 初投稿です。よろしくお願いいたします。

記事の概要とねらい

この記事では TypeScript で kintone プラグイン開発を行うためのテンプレート（自作）をご紹介します。

TypeScript による kintone カスタマイズ開発についてはサイボウズの公式サイトをはじめ、いくつかの事例が紹介されていますが、プラグインについては見当たらなかったため、自分で書いてみることにしました。

TypeScript を使った kintone 開発が盛り上がっていきますように！

対象となる方

kintone プラグイン開発の基本を理解している方
TypeScript の基本を理解している方

リポジトリ

テンプレートの概要

Webpack + Babel + TypeScript
ESLint + Prettier
サイボウズが提供している以下のライブラリを利用して開発を効率化
- @kintone/plugin-packer プラグインのパッケージング
- @kintone/plugin-uploader プラグインのアップロード

使いかた

前提

Node.js がインストールされていること
Yarn がインストールされていること

準備

下記のコマンドを実行してプロジェクトディレクトリを作成、必要なライブラリをインストールします。

git clone https://github.com/latica-jp/kintone-plugin-template-typescript.git dir_name
cd dir_name
yarn

プロジェクトのルートディレクトリで下記のコマンドを実行して .env ファイルを作成します。

cp .env.sample .env

作成された .env ファイルにアップロード先の kintone ドメインとユーザ／パスワードを指定します。

KINTONE_DOMAIN=xxxx.cybozu.com
KINTONE_USERNAME=kintone_user
KINTONE_PASSWORD=kintone_password

秘密鍵ファイルの作成

プロジェクトのルートディレクトリで以下のコマンドを実行すると、private.ppk ファイルが生成されます。プラグインのビルドを行う前に、必ず一度実行する必要があります。

yarn prepare

private.ppk ファイルはプラグインを一意に識別するためのファイルで、パッケージングされたプラグインに必ず含まれます。このファイルを削除して再生成した場合、パッケージングしたプラグインはコード内容が同一でも kintone には別のプラグインとして識別されますので、取り扱いには十分注意してください。

マニフェストファイルの更新

src/manifest.json を修正します。

設定内容は基本的に下記サイトに準拠します。
- kintone プラグイン開発手順 – cybozu developer network
- カスタマイズファイルが元のソースコードではなく、ビルド済みのファイルになる点に留意してください。

プラグインの作成

以下のコマンドで TypeScript コードのコンパイル、プラグインのパッケージングを実行して dist ディレクトリに出力します。

開発用ビルド
- yarn build
- 出力コードはデバッグ用のソースマップを含む
リリース用ビルド
- yarn release
- 出力コードは uglify され、ソースマップを含まない

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

プロジェクトのルートディレクトリで以下のコマンドを実行すると、dist/ ディレクトリに出力されたプラグインファイルを .env ファイルに指定した kintone 環境にアップロードします。

yarn upload

開発モード

プロジェクトのルートディレクトリで以下のコマンドを実行すると、コードの変更を監視し、変更を検知するたびに自動的にコードのコンパイル、プラグインのパッケージングとアップロードを行います。

コードの変更のたびにプラグインが更新されて kintone にアップロードされますので、効率的な開発を行えます。

yarn start

Disclaimer

kintone はプラグインアップロード用のAPI を備えていないため、@kintone/plugin-uploader は（なんと）puppeteer（headless の Google Chrome）を使用してプラグインをアップロードしています。そのためか、ときどきアップロードが失敗することがあります。
- 失敗した場合は（めげずに）リトライしてください。
自動ビルドとアップロードがうまくいかなくなることが（ときどき）あります。その場合はいったん ctrl-c でプロセスを停止して、再度 yarn start を再実行してください。

TypeScript についてのあれこれ

kintone カスタマイズで TypeScript を使用する場合、アプリのフィールドに対応する型を用意する必要があります。生成ツール（@kintone/dts-gen）があるとはいえ、ややハードルが高いと思いますが、プラグインはそれがない分 TypeScript に取り組みやすいかと思います。
VSCode は参照する TypeScript について VSCode 自身に同梱されたものと、プロジェクトにインストールされているもののどちらかを選択できます。ここでは、プロジェクトにインストールされたものを参照できるよう、リポジトリに設定ファイルを同梱しています。
- VSCode 上で以下の操作を行ってください
- 表示 -> コマンドパレット… -> TypeScript: TypeScript のバージョンを選択… -> ワークスペースのバージョンを使用
- ちなみに TypeScript 3.7 で導入された optional chaining を使用したくて、上記の設定を導入しました。
TypeScript のコンパイルは tsc ではなく babel で行っています。
まだまだ TypeScript 学習が足らず、設定など不要なものもあるかと思います。お気づきの方はご指摘いただけると助かります。
TypeScript 初心者でも、型の恩恵は十分に感じることができました。以下のメリットだけでも導入の価値はあると思っています。
- IDE の補完／チェックの恩恵が十全に受けられる
- 安全性の高いコードが書ける - とくに null / undefined エラーが激減するのが◎
API で取得した値のためにいちいち型を用意する代わりに汎用的な「JSON 型」を用意してそれで受ける、という手をよく使いました。このサンプルでは使用していませんが、参考に同梱してあります（こちら）。
kintone 関連で型ファイルが用意されていないものをとりあえず自分で付ける例（こちら）
- こういう小細工はちょこちょこ必要でした

参考資料

create-pluginを使ってプラグインの雛形を作成しよう！ – cybozu developer network
- 本テンプレートの初期コードはこちらを参考に create-plugin を使って生成したコードを使用しています
TypeScript や Webpack の設定については、以下のサイトを参考にさせていただいています。