Upload JavaScript and CSS files with Customize-uploader

Contents

Overview

This article introduces how to use the Customize-uploader (External link) tool. This tool automatically uploads JavaScript and CSS files to Kintone Apps whenever changes are made in the files.

What Is Customize-Uploader?

Customize-uploader is a CLI tool that uploads JavaScript and CSS customization files into Kintone Apps.
The tool is published on npm and is available for Windows, macOS, and Linux.
The source code is available on GitHub (External link) .

Check the engines property in package.json (External link) for the Node.js version requirements.
For example, if the following property is stated, version 10 or more is required.

1
2
3

"engines": {
  "node": ">=10"
}

Installation

Run this command to install customize-uploader globally using npm:

1

$ npm install -g @kintone/customize-uploader

Create the Manifest File

A manifest file needs to be created to use customize-uploader. It should contain the App ID of the App to upload the customization files to, as well as paths to the customization files themselves. Place the manifest file in the same hierarchy as the files to be uploaded. Update the manifest file with the following information.

  • app: App ID of the App to upload the files to
  • scope: Scope of customization ("ALL" || "ADMIN" || "NONE")
  • desktop: JavaScript and CSS files for PC ("js": [] || "css": [])
  • mobile: JavaScript and CSS files for mobile ("js": [] || "css": [])

When using a library from a CDN, input the URL of the library.

  • For example: https://js.kintone.com/jquery/3.3.1/jquery.min.js

An example of a completed customize-manifest.json file is shown below.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

{
  "app": "1",
  "scope": "ALL",
  "desktop": {
    "js": ["https://js.kintone.com/jquery/3.3.1/jquery.min.js", "sample.js"],
    "css": ["51-modern-default.css"]
  },
  "mobile": {
    "js": ["https://js.kintone.com/jquery/3.3.1/jquery.min.js"],
    "css": []
  }
}

If files are uploaded with the above customize-manifest.json file, the JavaScript and CSS Customization settings page should look like the following:

If there is only one single JavaScript file for a desktop customization, the manifest file will look as follows:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

{
  "app": "1",
  "scope": "ALL",
  "desktop": {
    "js": ["sample.js"],
    "css": []
  },
  "mobile": {
    "js": [],
    "css": []
  }
}

How to Upload JavaScript and CSS Files

Customize-uploader needs to specify the Kintone subdomain information when run.
There are three ways to enter the required information.

caution
Attention

Customize-uploader must be run by a user with Administrator privileges of the target App.

Direct Specification

Enter in the subdomain information, login name, and password as options in addition to the manifest file.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

# Move to hierarchy where manifest file is placed
$ cd sample_project
# Execute command
$ kintone-customize-uploader --base-url https://<subdomain>.kintone.com --username <username> --password <password> customize-manifest.json

sample.js has been uploaded!
JavaScript/CSS files have been uploaded!
Customize setting has been updated!
Wait for deploying completed...
Wait for deploying completed...
Setting has been deployed!

Interactive Specification

Specifying only the manifest file will prompt an interactive question and answer feature. Enter in the domain information, login name, and password.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

# Move to hierarchy where manifest file is placed
$ cd sample_project
# Execute command
$ kintone-customize-uploader customize-manifest.json

# Input the options interactively
? Input your kintone's domain (https://example.cybozu.com): https://<subdomain>.kintone.com
? Input your username: <username>
? Input your password: <password>
sample.js has been uploaded!
JavaScript/CSS files have been uploaded!
Customize setting has been updated!
Wait for deploying completed...
Wait for deploying completed...
Setting has been deployed!

Specification Using Environment Variables

Environment variables can be used by setting the Kintone subdomain, login name, password etc. as environment variables beforehand. This is useful when it is important for passwords and other sensitive information to not be displayed on the screen when running commands.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

# For Windows(PowerShell)
# Set Kintone information in the environment variable in advance
set-item "env:KINTONE_BASE_URL" https://<subdomain>.kintone.com
set-item "env:KINTONE_USERNAME" <username>
set-item "env:KINTONE_PASSWORD" <password>
set-item "env:HTTPS_PROXY or HTTP_PROXY" <Proxy Server>

# Move to hierarchy where manifest file is placed
$ cd sample_project
# Execute command
$ kintone-customize-uploader customize-manifest.json


# For Mac
# Set Kintone information in the environment variable in advance
export KINTONE_BASE_URL=https://<subdomain>.kintone.com
export KINTONE_USERNAME=<username>
export KINTONE_PASSWORD=<password>
export HTTPS_PROXY or HTTP_PROXY=<Proxy Server>

# Move to hierarchy where manifest file is placed
$ cd sample_project
# Execute command
$ kintone-customize-uploader customize-manifest.json

Optional Features

File Monitoring

A file can be uploaded automatically onto Kintone each time a change is made by monitoring file updates with the --watch option. Using this option prevents the need to continually re-upload customization files via the GUI.

1

$ kintone-customize-uploader --watch customize-manifest.json

To stop monitoring, cancel the command with ctrl + c.

Guest Space

Customization files can be uploaded to an App in a Guest Space using the --guest-space-id option.

1

$ kintone-customize-uploader --guest-space-id <Guest space ID> customize-manifest.json

Language Preference

The display language on the command line can be specified using the --lang option. Currently, either English (en) or Japanese (ja) can be specified.

1
2
3
4
5

# Setting to English
$ kintone-customize-uploader --lang en customize-manifest.json

# Setting to Japanese
$ kintone-customize-uploader --lang ja customize-manifest.json

Proxy Settings

When using a proxy server, proxy information can be entered using the --proxy option.

1
2
3
4

$ kintone-customize-uploader --proxy <Proxy Server> customize-manifest.json

# Using environment variables
$ kintone-customize-uploader --proxy $HTTP_PROXY customize-manifest.json

Sub-Commands

init

A customize-manifest.json file is generated using the init subcommand.

1
2
3
4
5
6

# Move to hierarchy where file to be uploaded is placed
$ kintone-customize-uploader init
? Input your app id: <appId>
? Select the scope of customization: "ALL" | "ADMIN" | "NONE"

dest/customize-manifest.json file has been created

import

Import App customization information into the customize-manifest.json file using the import subcommand.

1
2
3
4
5
6
7

$ kintone-customize-uploader import dest/customize-manifest.json
? Input your kintone's domain (https://example.cybozu.com): https://<subdomain>.kintone.com
? Input your username: <username>
? Input your password: [input is hidden] <password>
Generate customize-manifest.json from kintone app customize
Download Uploaded files on kintone app customize
Finish importing from kintone app customize

Reference