2
1

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

@the_red(赤座 久樹)

@kintone/dts-gen を複数アプリで一括実行するラッパーツール @goqoo/trunks を作った

2
Last updated at Posted at 2026-02-21

はじめに

kintone アプリの TypeScript 型定義を生成するには、公式の @kintone/dts-gen が便利です。
型を生成した後は大変大変便利にプログラミングできるんですが、dts-gen自体の使い勝手としては、複数アプリの型定義を一括生成できないのが辛いんですよね。。。

そこで、kintone 開発フレームワーク goqoo では、dts-genをラップして設定ファイルから複数アプリの型定義を一括生成する機能を組み込んでいました。しかし、この機能は goqoo を使っていないプロジェクトでも便利なはず...ということで、単独の CLI ツールとして切り出したのが @goqoo/trunks です。Goqoo on kintone シリーズに久々の新キャラ加入です :smile:

trunks でできること

  • 1コマンドで複数アプリの型定義を生成
  • TypeScript 形式の設定ファイルで型安全な設定（trunks.config.ts）
  • CLI オプションで設定ファイルなしのワンライナー実行も可能
  • Prettier による自動フォーマット（オプション）
  • 複数の認証方式に対応（パスワード、API トークン、OAuth）
  • プレビュー環境・ゲストスペースに対応

クイックスタート

init コマンドで始める（簡単）

npx @goqoo/trunks init

対話形式で設定ファイルを作成できます。ホスト名、アプリ（名前とID）、認証方式を順番に聞かれるので、答えていくだけで trunks.config.ts が完成します。

手動で設定ファイルを作成

プロジェクトルートに trunks.config.ts を作成します。

import { defineConfig } from '@goqoo/trunks';

export default defineConfig({
  host: 'your-subdomain.cybozu.com',
  apps: {
    customer: 123,   // アプリ名: アプリID
    order: 456,
    product: 789,
  },
  auth: { type: 'oauth' },
});

defineConfig を使うことで、設定の型補完が効くようになります。

コマンドを実行

npx @goqoo/trunks

型定義ファイルが生成される

dts/
├── customer-fields.d.ts
├── order-fields.d.ts
└── product-fields.d.ts

これだけです！

認証方式

trunks は3つの認証方式に対応しています。dts-genもこれらに対応していますが、使い勝手や安全性を担保するために色々と工夫しております。

パスワード認証

auth: { type: 'password' },

環境変数 KINTONE_USERNAME と KINTONE_PASSWORD から認証情報を読み取ります。未設定の場合は対話的に入力を求められます。

API トークン認証

auth: { type: 'api-token' },

環境変数 KINTONE_API_TOKEN からトークンを読み取ります。複数アプリの場合はカンマ区切りで指定できます。

OAuth 認証

auth: { type: 'oauth' },

Gyuma を使用した OAuth 認証です。実行するとブラウザが開き、認証フローが始まります。一度認証すればトークンがキャッシュされるので、2回目以降は一定期間スムーズに実行できます。（でもトークンの自動リフレッシュはあえてOFFにしています）

環境変数の設定

認証情報は .env ファイルに記述できます。trunks は自動的に .env を読み込みます。

# .env
KINTONE_USERNAME=your-username
KINTONE_PASSWORD=your-password
KINTONE_API_TOKEN=your-api-token

.env や設定ファイルに認証情報を書く場合は、必ず .gitignore に追加してコミットされないようにしてください。

設定オプション

import { defineConfig } from '@goqoo/trunks';

export default defineConfig({
  // 必須
  host: 'your-subdomain.cybozu.com',
  apps: {
    customer: 123,
    order: 456,
  },
  auth: { type: 'oauth' },

  // オプション
  outDir: 'dts',              // 出力ディレクトリ（デフォルト: "dts"）
  preview: false,             // プレビュー環境を使用（デフォルト: false）
  guestSpaceId: 5,            // ゲストスペース ID
  namespace: 'kintone.types', // TypeScript の namespace（デフォルト: "kintone.types"）
  format: true,               // Prettier でフォーマット（デフォルト: false）
});

プレビュー環境の利用

開発中のアプリ設定（まだ運用環境に反映していない変更）から型定義を生成したい場合は、preview: true を指定します。

export default defineConfig({
  // ...
  preview: true,
});

Prettier フォーマット

生成された型定義ファイルを Prettier でフォーマットしたい場合は、format: true を指定します。プロジェクトの Prettier 設定が自動的に適用されます。

export default defineConfig({
  // ...
  format: true,
});

ワンライナー実行

設定ファイルを作らずに、CLI オプションだけで実行することもできます。CI/CD や一時的な利用に便利です。

npx @goqoo/trunks \
  -H example.cybozu.com \
  -a customer:123 \
  -a order:456 \
  -A api-token \
  -t "$KINTONE_API_TOKEN"

主なオプション:

オプション 説明
-H, --host <host> kintone ホスト
-a, --app <name:id> アプリ（複数指定可）
-A, --auth-type <type> 認証方式: password, api-token, oauth
-u, --username ユーザー名（password用）
-p, --password パスワード（password用）
-t, --api-token APIトークン（api-token用）
-o, --out-dir 出力ディレクトリ
-f, --format Prettierでフォーマット

全オプションは trunks --help で確認できます。

実行後

これはdts-genユーザーなら普通に知っていることですが、改めて。

生成される型定義

アプリ名 customer（ID: 123）の場合、以下のような型定義が生成されます。

// dts/customer-fields.d.ts
declare namespace kintone.types {
  interface CustomerFields {
    companyName: kintone.fieldTypes.SingleLineText;
    email: kintone.fieldTypes.Link;
    // ...
  }
  interface SavedCustomerFields extends CustomerFields {
    $id: kintone.fieldTypes.Id;
    $revision: kintone.fieldTypes.Revision;
    // ...
  }
}
  • CustomerFields: レコード作成・更新時に使う型（システムフィールドなし）
  • SavedCustomerFields: 取得したレコードの型（システムフィールドあり）

実際の使い方

kintone REST API Client と組み合わせる

import { KintoneRestAPIClient } from '@kintone/rest-api-client';

const client = new KintoneRestAPIClient({
  baseUrl: 'https://your-subdomain.cybozu.com',
  auth: { apiToken: process.env.KINTONE_API_TOKEN },
});

// 型安全にレコードを取得
type CustomerRecord = kintone.types.SavedCustomerFields
const { records } = await client.record.getRecords<CustomerRecord>({
  app: 123,
});

// companyName は SingleLineText 型として推論される
records.forEach(record => {
  console.log(record.companyName.value);
});

CI/CD で型定義を自動更新

GitHub Actions などで定期的に型定義を更新することもできます。
（これはAIが提案しただけの設定ファイルで、自分ではまだ試してないがw）

# .github/workflows/update-types.yml
name: Update kintone types

on:
  schedule:
    - cron: '0 0 * * 1'  # 毎週月曜日
  workflow_dispatch:

jobs:
  update:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - run: npm ci
      - run: npx @goqoo/trunks
        env:
          KINTONE_API_TOKEN: ${{ secrets.KINTONE_API_TOKEN }}
      - uses: peter-evans/create-pull-request@v5
        with:
          commit-message: 'chore: update kintone type definitions'
          title: 'Update kintone type definitions'
          branch: update-kintone-types

まとめ

trunks を使えば、複数の kintone アプリの型定義を簡単に一括生成できます。

  • 設定ファイル1つで複数アプリに対応
  • CLI オプションでワンライナー実行も可能
  • OAuth / API トークン / パスワード認証をサポート
  • Prettier 自動フォーマット対応

kintone の TypeScript 開発をより快適にするツールとして、ぜひ使ってみてください。
フィードバックや Issue、PR も歓迎です！

ではまた！

2
1
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
Sign upLogin
2
1

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?