kintoneのJavaScriptカスタマイズを始めてしばらくすると、設計面で迷う場面が出てきます。
「便利な機能をいくつか入れたいけど、ファイルは1つにまとめるべき？ それとも機能ごとに分けるべき？」
kintoneのJSファイルは「ファイルをアップロードする」という形式をとります。 この管理方法を間違えると、後から「どのコードがどこで動いているかわからない…」ということになってしまいます。
今回は、メンテナンス性を高める「JSファイルの分割とアップロード」の考え方について、カスタマイズ初級者（IT専門職ではない業務担当者、市民開発者）の立場でまとめました。
- 結論：カスタマイズ初級者は、JSファイルを「機能単位」で分けるのが基本
- 「kintoneのイベント仕様」
- アップロード時に知っておくべき「並び順」のルール
- 名前衝突を防ぐ「おまじない」
- まとめ：綺麗な管理が「安定稼働」への近道
結論：カスタマイズ初級者は、JSファイルを「機能単位」で分けるのが基本
kintoneカスタマイズを学び始めたばかりの方や、現場の課題を自ら解決する市民開発者の方は、「目的の機能ごとにファイルを作成してアップロードする」 方法が基本です。
なぜ「機能単位」で分けるのか？
管理がしやすい ファイル名を見ただけで何をするプログラムか一目でわかります。修正が必要な時も、迷わず対象ファイルを開けます。
機能の「ON/OFF」が簡単 特定の機能が不要になった際、kintoneの設定画面からそのファイルを外すだけで済みます。正常に動いている他のコードを触らずに済むため、「修正して別の部分が壊れた」というリスクがありません。
使い回しができる 別のアプリを作る際、便利な機能のファイルだけをそのままコピーして流用できます。「以前作ったあの機能、今回も使えそう」という時に、ファイルをまるごと持っていくだけで済むのは大きなメリットです。
アップロードできるファイル数の上限は30個
kintoneの仕様でアップロードできるファイル数の上限は30個です。 カスタマイズ初級者が作成するJSファイルの数は少なく、機能もシンプルなものという想定です。 上限に近い多数のJSファイルや、単独のJSファイルで完結しないような複雑なカスタマイズの場合は、考え方も変わります。
1つのアプリにつき、JavaScriptファイル、CSSファイルは、PC用とスマートフォン用でそれぞれ30個までです。 1つのファイルあたりのファイルサイズの上限は、20MBまでです。
「kintoneのイベント仕様」
「同じイベント（例：保存前イベント）を複数のファイルに書いたら、衝突して動かなくなるのでは？」という心配はありません。
kintoneでは複数のファイルで同じイベント（例：app.record.create.show）を登録しても、すべてのハンドラーが順番に実行されます。
この点については、サイボウズの公式開発者向けドキュメント（cybozu developer network）で次の記載があります。
「イベントハンドラーは追加されていくのみで、上書きされることはありません。これはJavaScript全般の仕様で、kintone JavaScript APIでもこの仕様に準じます。」
出典： https://cybozu.dev/ja/kintone/docs/js-api/events/event-handling/
アップロード時に知っておくべき「並び順」のルール
ファイルを分けてアップロードする際、1点だけ注意が必要なのが 「実行順序」 です。
kintoneのJavaScriptは、設定画面で 上から登録されている順番 に読み込まれ、実行されます。
これはkintone公式ヘルプに明記されている仕様です。
「複数のファイルを取り込んだ場合、ファイルは上から順番に読み込まれます。また、ファイルの順番は、ファイル名の左側にある［ドラッグして並び替え］アイコンをドラッグアンドドロップして変更できます。」
名前衝突を防ぐ「おまじない」
ファイルを分割する際に1つ注意したいのが、変数名の重複です。JavaScriptでは、ファイルをまたいで同じ名前のグローバル変数を宣言すると、後から読み込まれた方が上書きしてしまい、予期しない動作の原因になります。
これを防ぐために、コード全体を以下の 「即時実行関数（IIFE）」 で囲むのが鉄則です。
(function() { 'use strict'; // ここにコードを書く // この中で宣言した変数は外部に漏れないため、 // 他のファイルと名前が重複しても影響を受けません })();
この書き方は「カプセル化」と呼ばれ、kintone公式のコーディングガイドラインでも推奨されています。
「グローバル変数の使用は避け、即時関数のスコープ内またはブロックスコープ内で変数を定義してください。」
ファイルを分割する際は、必ずこの形式で作成します。
まとめ：綺麗な管理が「安定稼働」への近道
今回のポイントを整理します。
- 機能ごとにファイルを作る（1機能 = 1ファイルが基本）
- わかりやすい名前をつける（例：
auto_fill_name.js、auto_numbering.js） - 共通設定や共通関数は一番上に配置する（公式仕様：上から順に読み込まれる）
- コードは即時実行関数
(function(){ })();で囲む（公式ガイドライン推奨）
以上、kintoneにおけるJavaScriptファイルのアップロードと管理の考え方でした。
