kintone Best Practiceを使用したプロジェクト作成手順

環境、ツール

kintone
kintone-cli 0.1.5
kintone UI Component
kintone-js-sdk
kintone-rest-api-client
VisualStudioCode
kintone-extension for VSCode

kintone-cli

kintone/kintone-cli

kintoneの開発のためのコマンドラインツールです。npmでインストールできます。

プロジェクトディレクトリに、開発に必要なひな形を作ってくれます。

また、kintoneへのデプロイなどもコマンドラインからできるようになります。VisualStuidioCodeのターミナルからアップロードできるので便利です。

kintone UI Component

HTMLなどのDOM要素を生成するコンポーネントです。kintoneっぽいUIを生成できます。

kintone-cliでプロジェクトファイルを作るとき、利用するかどうか確認が入ります。Yesと答えるとwebpackの依存としてインストールされます。

kintone-js-sdk (deprecated)

GitHub - kintone/kintoneUtilityの後継のようです。便利なメソッドが用意されているライブラリ。おそらくkintone開発する人なら自前でこうしたメソッドなどのテンプレートを用意して使い回している人が多いと思います。標準に合わせることで、他の人と共通認識を持ちやすい、新しい人でもすぐ入れる、などのメリットがあります。 kintone-cliでプロジェクトファイルを作るとき、利用するかどうか確認が入ります。Yesと答えるとwebpackの依存としてインストールされます。

kinone rest-api client

developer.cybozu.io

JS-SDKが非推奨になって、こちらに統合されたようです。

kintone-extension for VSCode

VSCode用の機能拡張です。UI Componentやjs-sdkなどの補完が使えるようになります。

初期設定、準備

kintone-cliをグローバルインストール

Githubの公式リポジトリにはnpm install -g git://github.com/kintone-labs/kintone-cli.gitでインストールするように指示があるけれど、私の環境では+httpsがないとインストールできない（サーバーが見つからない）

$ npm install -g git+https://github.com/kintone-labs/kintone-cli.git

VisualStudioCodeをインストール

インストール後、kintone-extensionをインストールします。

ここまでの作業（kintone-cliのインストールやVSCodeのインストール）は、PCごとに1回やれば、次回新規プロジェクトを作成する時は省略できます。

プロジェクト作成手順

プロジェクトを初期化し、テンプレートを配置する

VisualStudioCodeのターミナルで作業ディレクトリに移動し、初期化コマンドを使います。

仮に作業ディレクトリC:/Users/Documentsでkintone-cli init --install すると、プロジェクトディレクトリはC:/Users/Documents/someProjectNameになります。

$ kintone-cli init --install
//または
$ kintone-cli init [--install] [--quick] [--project-name <someProjectName>]

質問に答えていきます。—quickオプションを追加すると、質問にすべてデフォルトで答えたのと同じになります。

? Project name someProjectName
? Version 0.0.1
? Description kintone customization project
? Author aibri
? License MIT
? Do you want to use @kintone/kintone-ui-component? Yes
? Do you want to use @kintone/kintone-js-sdk? <s>Yes</s>No //kintone-js-sdkがdeprecatedになったため、Noにして別途rest-api-clientを入れた方がいいように思います。

余談ですが、プロジェクト初期化後のメッセージに

To createnew app, use:
kintone-cli create-template

とあります。実際にはcreate-templateを使うにはプロジェクトディレクトリ内に移動しないといけないので

To createnew app, use:
cd <project name>
kintone-cli create-template

の方がいいと思います

cd

プロジェクトディレクトリが生成されるので、cd <projectName>でプロジェクトディレクトリ内に移動します。以後のターミナルでの作業はこのディレクトリで行います。

rest-api-client

CDNで読み込む方法と、npmでインストールする方法とがあります。NPMの場合は以下の手順です。

$ npm install @kintone/rest-api-client

公式によればrequireして読み込め、とあります。

const { KintoneRestAPIClient } = require("@kintone/rest-api-client");

CDNの場合は、KintoneRestAPIClient がグローバルオブジェクトとして読み込まれるらしいので、こっちの方がお手軽かもしれません。後述する「外部ライブラリの追加」でCDNのURLを指定することになります。

githubへpush

プロジェクトディレクトリの直下がGit repositoryとして初期化されますので、必要ならGithubにリポジトリを作成し、アップロードします。

git remote add origin https://foobar.baz
git push -u origin master

アプリテンプレートを作る

アプリを作成するためのひな形を作成します。

$ kintone-cli create-template

kintone-cliではsomeProjectName/someAppNameというディレクトリ構成になります。

複数のアプリを作るなら再度kintone-cli create-templateすることでsomeProjectName/someAppName2のように増やすことができます。

? What type of app you want to create ? Customization
? Do you want to set authentication credentials ? Yes
? Do you want to use React ? No
? Do you want to use TypeScript ? No
? Do you want to use webpack ? Yes
? What is the entry for webpack ? index.js
? What is the app name ? someAppName
? Do you want to use @cybozu/eslint-config for syntax checking ? Yes
? What is the scope of customization ? ALL

ReactとTypeScriptがデフォルトでYesになっているので注意してください（私は使っていないのでいつも気をつけています）。

外部ライブラリの追加

外部ライブラリのCDNなどを読み込む場合は、someProjectName/someAppName/config.jsonの”uploadConfig”に項目を追加します。

"uploadConfig":{
    "desktop":{
        "js":[
            "someCdnUrl1",
            "someCdnUrl2",
            "someAppName/dist/index.min.js"
        ],
        "css":[]
    },
    "mobile":{
        "js":[
            "someCdnUrl1",
            "someCdnUrl2",
            "someAppName/dist/index.min.js"
            ],
        "css":[]
    }
}

外部ライブラリを追加してESLint等のチェックで「この変数は定義されていません」というエラーが出る場合、someProjectName/someAppName/webpack.config.jsで”externals”を追加するとエラーを回避できるようです。

externals{
    jquery: 'jQuery'
}

auth.jsonの確認

kintoneの権限情報がsomeProjectName/someAppName/auth.jsonに書き込まれています。これが正しくないとアップロードできないので、確認しておきましょう。

{
  "username": "some_user_name",
  "password": "some_password",
  "domain": "some_subdomain.cybozu.com"
}

source-mapの設定

デフォルトのsomeProjectName/someAppName/webpack.config.jsではdevelopmentモードの時にsource-mapを使用するようになっているようです。私の場合はinline-source-mapの方がいいような気がするので値を書き換えています。

また、deploy時にinline-source-mapを使うこともあるので、その場合はそれも追記します。

module.exports = (env, argv) => {
  if (argv.mode === 'development') {
    config.devtool = 'inline-source-map';
  }

  if (argv.mode === 'production') {
    //...
    config.devtool = 'inline-source-map';
  }
  return [config];
};

その他設定ファイル

「EditorConfig」「ESLint」「prettier」等の機能拡張を入れている場合は、必要に応じて追加 / 編集します。

someProjectName/.editorconfig
someProjectName/.eslintrc.js
someProjectName/.prettierrc
someProjectName/someAppName/.babelrc

jsのテンプレートを微修正

コーディングの起点になるのは、someProjectName/someAppName/source/index.jsです。これは someProjectName/someAppName/webpack.config.jsに記述されています。

const config = {
    entry: path.resolve('someAppName/source/index.js')
}

jQueryの導入

jQuery を導入するならjQuery.noConflictとfunction($)を書き換えます。

jQuery.noConflict();
(function($){
'use strict'

//your code

}

Vue.jsの導入

npm install --save vue

jsの方にはimportを追加します。

import Vue from 'vue';

開発ドメインがある場合のappID記述方法

ドメインの記述方法はこれを参考にしています。

kintoneの本番環境・開発環境で異なるアプリIDを自動判定する方法 - Qiita

  const environments = {
    '<開発ドメイン>.cybozu.com': [{
      // 開発環境
      customer: 1,
      order: 2,
    }, ],
    '<本番ドメイン>.cybozu.com': [{
        // 本番環境
        customer: 11,
        order: 22,
      },
      {
        // ステージング環境
        customer: 111,
        order: 222,
      },
    ],
  }
  // まず現在のドメイン名で絞る
  const spaces = environments[location.hostname]
  // 次に現在のアプリIDを含む環境を1つ抽出
  const app = spaces.find(s => Object.values(s).some(appId => appId === kintone.app.getId()))
  // app.customer, app.orderなど、環境に応じてappIdの変数が自動変更される

キャッシュ？

実際にはまだ使ったことないけど、APIコールを減らすためのキャッシュ変数を用意したらどうかと思っています。

  // kintoneから取得したデータをキャッシュしてアクセスを減らすための変数
  let kintone_cache;

コーディング

ここからが実際のコーディング本番です。

VSCodeの「kintone-extension for VSCode 」を入れていれば、コード補完により、候補が表示されます。

例えば以下のような単語を打つと候補が表示されます。

動作確認、デプロイ

kintone-cliには動作確認やデプロイに必要なツールが用意されています。

kintone-cli dev

devコマンドはローカルのwebサーバーを立ち上げ、kintoneの設定にローカルファイルへのリンクを書き込むことで、JavaScriptが自分だけに適用される環境を作ります。その際、webpackのmodeは developmentになります。

kintone-cli dev [--app-name <someAppName>]

kintone-cli devを実行した後、一度メッセージが出て止まります。

Please open this link in your browser to trust kintone Customization files:

   https://some_local_url

Then, press any key to continue:

このタイミングでブラウザからhttps://some_local_urlを開きます。ターミナルの文字列がリンクになっていればそれをクリックして開くこともできます。ブラウザがローカルファイルへのアクセス許可を求めてくるので、許可します。その後、何かキーを押して処理を進めます。

ローカルwebサーバーが起動し、kintoneにlocalのJavaScriptを渡します。そのため、更新してbuildしたファイルがそのまますぐkintoneに適用されます。たしかに便利です。

ただこのコマンドでは、kintone側にローカルサーバーのIPアドレスを書き込むので実際に稼働中のサーバーで使用するのは少々躊躇われる部分もあります。他の人から見た時にどういう影響が出ているのか、ちょっと不安です。

Chromeの「オーバーライド機能」が便利だと聞いたので、個人的にはそちらを使うことを検討しています。JSも書き換えられるようなので、「サーバーに手を加えず自分だけに適用」ということが実現できそうです。

kintone-cli build

kintone-cli build [--app-name <App Name>]

buildコマンドはビルドだけしてアップロードはしない、というコマンドです。kintone-cli dev --watchと併用するということだと思います。

deployコマンドもビルドする機能が含まれていますので、deploy前に明示的にkintone-cli buildする必要はありません。

kintone-cli deploy

kintone-cli deploy [--app-name <App Name>]

webpackのmode = productionでビルドし、auth.jsonの情報を使ってkintoneにアップロードします。VisualStudioCodeのターミナルからすぐにアップロードできるので便利です。

Because We Love Happy Coding

フリーライターからエンジニア × 講師。発信力だけあり余ってる感じ