Skip to content

Latest commit

 

History

History
293 lines (252 loc) · 10 KB

README.md

File metadata and controls

293 lines (252 loc) · 10 KB
Raw

kintone CLI(β)

A tool to quickly start developing with kintone

ⓘ This tool has been migrated from git://github.com/kintone/kintone-cli

Warning

The maintenance of kintone CLI will end on 31 December 2024. For more details, please refer to this announcement.

Installation

npm install -g https://github.com/kintone-labs/kintone-cli.git
or
yarn global add https://github.com/kintone-labs/kintone-cli.git

Sometimes depending on the npm version, the error message "command not found" will be displayed. In that case, please try with the yarn command instead.

Quickstart

To quickly start with a minimum project, follow the instruction here

Usage

When working with kintone, developers usually follow this flow:

  1. Initialize Project
  2. Create Template
  3. Start dev locally
  4. Build source code
  5. Deploy to kintone

1. Initialize Project

kintone-cli init [--install] [--quick] [--project-name <projectName>]

Kintone CLI will require following input information. If any piece of info is skipped default value will be auto assigned:

  • Project name
  • Project version
  • Project description
  • Project author
  • Project license
  • Optional dependencies:
    • @kintone/rest-api-client (y/n)
    • @kintone/kintone-ui-component (y/n)

After all the above info is inputted, cli will initialize the following folder structure:

<Project Name>
    ├── package.json
    └── .gitignore

If --install flag is specified, Kintone CLI will run npm install after initializing folder structure.

If --quick flag is specified, Kintone CLI will init a project with the following default parameter:

--project-name: 'kintone-customization-project'

In addition, this boolean option will be set to true:

--install

Ask if user wants to create-template after finishing init project.

2. Create customization / plugin template

Go to the project forder.

cd {project name}

Create a JS customization or a plugin project structure under the project folder.

kintone-cli create-template
    [--quick]
    [--preset React|ReactTS]
    [--set-auth]
    [--domain <domain>]
    [--username <username>]
    [--password <password>]
    [--type Customization|Plugin]
    [--scope ALL|ADMIN|NONE]
    [--use-typescript]
    [--use-webpack]
    [--use-react]
    [--use-cybozu-lint]
    [--app-name <appName>]
    [--app-id <App ID (for Customization) >]

The --scope flag is for setting the scope of customization; therefore, setting the value of --scope when creating a plugin template will have no effect on the app.

If the flag --quick is present, CLI will set default values for the following options:

--type: 'Customization'
--app-name: `kintone-${Date.now()}`
--scope: 'ALL'

In addition, the below boolean options will be set to false:

--set-auth
--use-typescript
--use-webpack
--use-cybozu-lint
--use-react

You can override some options even when the --quick flag is present:

--type
--app-name
--scope

Below is an example of overriding some of the --quick default values:

kintone-cli create-template --quick --app-name Sample-App --scope ADMIN

If value is set for flag --preset, CLI will use preset variable to create folder. If both flag --preset and --quick is set, the config will be merge from both --quick config and --preset config.

Current supported preset:

  • React
  • ReactTS

CLI will require following input information. If any piece of info is skipped default value will be auto assigned:

  • Type: customization or plugin
  • Name
  • If --set-auth flag was specified, input Authentication settings:
    • Domain
    • Username
    • Password
    • Proxy
  • Using typescript (y/n)
  • Using React (y/n)
  • If using React, ask if using Webpack (y/n)
  • If using Webpack, config webpack:
    • Entry
  • Use ESLint (y/n)
  • If selecting 'Customization', configure kintone App ID

After the above information is inputted, the following folder structure will be created:

<Customization|Plugin Name>
    ├── source
    │   ├── js
    │   │   ├── script.js
    │   │   └── config.js   // this file is created only when developing Plugin
    │   └── css
    │       ├── style.css
    │       └── config.css  // this file is created only when developing Plugin
    ├── dist                // this folder is created only when using webpack
    ├── pluginConfig.html   // this file is created only when developing Plugin
    ├── icon.png            // this file is created only when developing Plugin
    ├── config.json
    ├── auth.json
    ├── tsconfig.json       // if using TypeScript
    ├── .eslintrc.js        // if using ESLint
    └── webpack.config.js   // if using webpack

Sample config.json file:

{
    "appID": YOUR_APP_ID,
    "appName": "YOUR_APP_NAME",
    "type": "Plugin",
    "uploadConfig": {
        "desktop": {
            "js": [
                "{YOUR_APP_NAME}/{PATH_TO_YOUR_JS_FILE}"
            ],
            "css": [
                "{YOUR_APP_NAME}/{PATH_TO_YOUR_CSS_FILE}"
            ]
        },
        "mobile": {
            "js": [
                "{YOUR_APP_NAME}/{PATH_TO_YOUR_JS_FILE_FOR_MOBILE}"
            ],
            "css": [
                "{YOUR_APP_NAME}/{PATH_TO_YOUR_CSS_FILE_FOR_MOBILE}"
            ]
        },
        // In case of Plugin
        "config": {
            "html": "{YOUR_APP_NAME}/{PATH_TO_YOUR_CONFIG_HTML}",
            "js": "{YOUR_APP_NAME}/{PATH_TO_YOUR_CONFIG_JS}"
        },
        "icon": "{YOUR_APP_NAME}/{PATH_TO_YOUR_ICON}",
        "version": "{PLUGIN_VERSION}"// Plugin version number (integer) e.g. "version": 1
    }
}

Config.json fields

Field Required Type Description
appName Yes String Customization / Plugin name
appID Customization only Integer App ID to deploy Customization
type Yes String App's type:
  • Customization
  • Plugin
scope Customization only String Customization scope
  • ALL: Affect all users
  • ADMIN: Affect only App administrators
  • NONE: Disable
uploadConfig Yes Object Config for build, deploy command
uploadConfig.desktop Yes Object Config for kintone desktop
uploadConfig.desktop.js Yes Array<String> JS files / URLs to upload to kintone desktop.
uploadConfig.desktop.css Yes Array<String> CSS files / URLs to upload to kintone desktop.
uploadConfig.mobile Object Config for kintone mobile
uploadConfig.mobile.js Array<String> JS files / URLs to upload to kintone mobile.
uploadConfig.mobile.css Array<String> CSS files / URLs to upload to kintone mobile.
uploadConfig.config Plugin only Object Config for kintone plugin's config page
uploadConfig.config.html String HTML for kintone plugin's config page
uploadConfig.config.js Array<String> JS files / URLs for kintone plugin's config page
uploadConfig.config.css Array<String> CSS files / URLs for kintone plugin's config page
uploadConfig.config.required_params Array<String> An array of parameters that are required to be filled in in the Plug-in Settings page. Must be between 1 to 64 ASCII characters.
uploadConfig.icon Plugin only String Plugin's icon
uploadConfig.version Plugin only String or Integer Plugin's version

3. Start dev

kintone-cli dev [--app-name <App Name>] [--watch] [--localhost]

Deploy customization files|plugin in to test domains for debugging. Using local web server to serve js/css files directly from project source files.

If --watch flag is specified and customization|plugin uses webpack, each time a source file is changed it is automatically built. Please note that html file and img file for icon are not changed automatically. Only js/css files are changed.

The --localhost parameter:

  • The last IP on the list will be chosen if there is no https://127.0.0.1:8000.
  • Don't specify --localhost parameter if you want to display the IP list for choosing.

4. Build source code

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

If a customization|plugin folder contains a webpack.config.js, cli will build by using their webpack.config.js file first.

If a folder is also a plugin folder, CLI will generate manifest.json based on config.json, then package source files into a plugin .zip file according to manifest.json

5. Deploy to kintone

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

Customizations|plugins will be deployed using their config.json and auth.json file.

Other functions

1. Lint code

Check/fix code (using ＠cybozu/eslint-config) kintone-cli lint [--app-name <App Name>] [--fix]

Result:

  • {File name} ( {File Path} ):
    • {Error 1}:
      • Line {Line Number 1}
      • Line {Line Number 2}
    • {Error 2}:
      • Line {Line Number 1}
      • Line {Line Number 2}

If --fix flag is specified, cli will also attempt to fix all auto-fixable problems in source code

2. Import / export data (WIP)

3. Auth

kintone-cli auth
    [--app-name <appName>]
    [--domain <domain>]
    [--username <username>]
    [--password <password>]
    [--app-id <appID>]
    [--use-proxy]
    [--proxy <proxyURL>]

Save authentication credentials into auth.json file.

Flag --app-name, --domain, --username, --password is required.

Flag --proxy is required when the flag --use-proxy is set.

Contributing

We welcome contributions to kintone-cli. If you have a question, feature request, or bug report, please register GitHub issue. Pull requests are also welcome when you find trivial bugs, typos or feature requests.

License

MIT License

Copyright

Copyright(c) Cybozu, Inc.