@zygapp/kintone-customize-devtool

kintone カスタマイズ開発を超簡単に

Vite + HMR で kintone カスタマイズ開発を快適に。 コードを保存すれば、即座に kintone 画面に反映されます。

Features

| | | |---|---| | Hot Module Replacement | コード変更が即座に kintone 画面に反映。ページリロード不要。 | | モダンフレームワーク対応 | React / Vue / Svelte / Vanilla に対応 | | TypeScript サポート | 型安全な開発環境を標準提供 | | ESLint 統合 | フレームワークに応じた ESLint 設定を自動生成 | | シンプルなワークフロー | init → dev → build → deploy の 4 ステップ | | クロスプラットフォーム | macOS / Linux / Windows（Intel & ARM） |

Quick Start

1. インストール

npm install -g @zygapp/kintone-customize-devtool

2. プロジェクト作成

kcdev init my-app
cd my-app

対話形式で以下を設定します：

• kintone ドメイン（例：example.cybozu.com）
• アプリ ID
• フレームワーク（React / Vue / Svelte / Vanilla）
• 言語（TypeScript / JavaScript）
• カスタマイズ対象（デスクトップ / モバイル）
• 適用範囲（ALL / ADMIN / NONE）
• 認証情報

3. 開発開始

kcdev dev

ブラウザが自動で開きます。https://localhost:3000 の SSL 証明書を許可すると、kintone アプリにリダイレクトされます。

4. 本番デプロイ

kcdev build && kcdev deploy

Commands

kcdev init [project-name]

新しいプロジェクトを初期化します。

kcdev init my-app

オプション:

| オプション | 説明 | |-----------|------| | -d, --domain | kintone ドメイン（自動補完対応） | | -a, --app | アプリ ID | | -f, --framework | フレームワーク（react / vue / svelte / vanilla） | | -l, --language | 言語（typescript / javascript） | | -o, --output | 出力ファイル名（拡張子なし、デフォルト: customize） | | -u, --username | kintone ユーザー名 | | -p, --password | kintone パスワード | | -m, --package-manager | パッケージマネージャー（npm / pnpm / yarn / bun） | | --desktop | デスクトップを対象に含める | | --mobile | モバイルを対象に含める | | -s, --scope | 適用範囲（all / admin / none） | | --create-dir | プロジェクトディレクトリを作成 | | --no-create-dir | カレントディレクトリに展開 |

kcdev dev

開発サーバーを起動し、ローダーを kintone に自動デプロイします。

既存のカスタマイズがある場合は確認プロンプトが表示されます。

kcdev dev

オプション:

| オプション | 説明 | |-----------|------| | --skip-deploy | ローダーのデプロイをスキップ（2回目以降の起動時に便利） | | --no-browser | ブラウザを自動で開かない | | -f, --force | 既存カスタマイズの確認をスキップして上書き | | -p, --preview | プレビュー環境のみにデプロイ（本番反映しない） |

kcdev build

本番用ビルドを生成します。IIFE 形式で dist/ に出力されます。

console.error 以外の console.* と debugger は自動的に削除されます。

ビルド前にバージョン更新の確認が表示されます（パッチ / マイナー / メジャー / カスタム）。

kcdev build

オプション:

| オプション | 説明 | |-----------|------| | --no-minify | minify を無効化（デバッグ用） | | --skip-version | バージョン確認をスキップ |

出力ファイル:

• dist/customize.js（または設定した出力ファイル名）
• dist/customize.css（CSS がある場合）

kcdev deploy

ビルド成果物を kintone にデプロイします。

dist/ が存在しない場合は自動でビルドを実行します。存在する場合は再ビルドするか確認が表示されます。

既存のカスタマイズがある場合は確認プロンプトが表示されます。

kcdev deploy

オプション:

| オプション | 説明 | |-----------|------| | -f, --force | 既存カスタマイズの確認をスキップして上書き | | -p, --preview | プレビュー環境のみにデプロイ（本番反映しない） | | --skip-version | バージョン確認をスキップ |

kcdev types

TypeScript プロジェクトで、kintone アプリのフィールド型定義を生成します。

kcdev types

@kintone/dts-gen を使用して src/types/kintone.d.ts を生成します。

Note: TypeScript プロジェクトでは、kcdev init 実行時に自動的に型定義が生成されます。フィールドを追加・変更した場合は、このコマンドで再生成してください。

kcdev config

対話形式でプロジェクト設定を変更します。

kcdev config

設定可能な項目:

• kintone 接続設定（ドメイン、アプリ ID、認証情報）
• ターゲット（デスクトップ / モバイル）
• 適用範囲（ALL / ADMIN / NONE）
• 出力ファイル名
• エントリーファイル
• フレームワーク変更（依存パッケージの入れ替え、設定ファイルの再生成を自動実行）

kcdev upgrade

プロジェクトの設定ファイルと依存パッケージを最新の kcdev 仕様に更新します。

kcdev upgrade

処理内容:

• Vite 設定の更新（Vite 8 対応: rolldownOptions, Oxc）
• 依存パッケージを最新バージョンに更新

Project Structure

my-app/
├── src/
│   ├── main.tsx          # エントリーポイント
│   ├── App.tsx           # メインコンポーネント
│   └── style.css         # スタイル
├── .kcdev/
│   ├── config.json       # 設定ファイル
│   ├── vite.config.ts    # Vite 設定（自動生成）
│   ├── eslint.config.js  # ESLint 設定（自動生成）
│   ├── index.html        # 開発用 HTML
│   ├── certs/            # SSL 証明書
│   └── managed/          # ローダー（自動生成）
├── dist/                 # ビルド出力
├── package.json
├── .env                  # 認証情報
└── .gitignore

Authentication

認証情報は以下の優先順位で取得されます：

1. .env ファイル（推奨）

KCDEV_USERNAME=your-username
KCDEV_PASSWORD=your-password

2. .kcdev/config.json

{
  "kintone": {
    "auth": {
      "username": "your-username",
      "password": "your-password"
    }
  }
}

Note: .env と .kcdev/config.json は .gitignore に追加されます。認証情報をリポジトリにコミットしないでください。

SSL Certificate

開発サーバーは HTTPS で起動します。初回アクセス時に自己署名証明書の警告が表示されます。

証明書を信頼する方法

1. https://localhost:3000 にアクセス
2. ブラウザの警告画面で「詳細設定」→「安全でないサイトへ進む」を選択
3. または、OS の証明書ストアに .kcdev/certs/localhost.pem を登録

How It Works

kintone
  ↓ classic script
kintone-dev-loader.js
  ↓ dynamic import
Vite dev server (ESM + HMR)
  ↓
src/main.*

kintone は classic script のみ対応ですが、kcdev は開発時に Vite の ESM + HMR を活用できるようローダーを自動生成・デプロイします。

開発者が意識するのは src/ 以下のコードだけ。 ローダーや設定ファイルは kcdev が管理します。

CLI について

kcdev は Go で実装されたネイティブバイナリです。npm 経由でインストールすると、OS・アーキテクチャに応じた実行ファイルが自動選択されます。高速な起動と安定した動作を実現しています。

Requirements

• Node.js 18 以上
• kintone 環境（cybozu.com）

Supported Platforms

| OS | Architecture | |----|--------------| | macOS | Intel (x64) / Apple Silicon (arm64) | | Linux | x64 / arm64 | | Windows | x64 / arm64 |

Troubleshooting

HMR が動作しない

• https://localhost:3000 の SSL 証明書を許可しているか確認してください
• ブラウザの開発者ツールでコンソールエラーを確認してください

ローダーのデプロイに失敗する

• .env または .kcdev/config.json の認証情報を確認してください
• kintone アプリの管理権限があるか確認してください

Windows で証明書エラーが出る

• PowerShell を管理者権限で実行し、証明書をインポートしてください
• または、ブラウザで https://localhost:3000 にアクセスして手動で許可してください

License

MIT