Improve Code Quality with ESLint

Contents

Overview

This article explains how to set up ESLint for use with developing Kintone customizations. It is recommended to use @cybozu/eslint-config with this setup.

ESLint is a tool to check JavaScript syntax, published by Nicholas C. Zakas as an open-source project in 2013. Users can create, extend, and add their own rules to ESLint, or use any other published rule set.

One of the most well-known rule sets is eslint-config-google (External link) published by Google which is also widely used for general JavaScript development.

What is @cybozu/eslint-config?

@cybozu/eslint-config is an ESLint rule set for Kintone development created by Kintone developers.

Features of @cybozu/eslint-config are as follows:

  • Maintains the quality of code for Kintone development.
  • ESLint is originally a command line tool but can be installed on supported editors as an extension. This makes it possible to check code in real time while developing.
  • When using ESLint in the command line, the autofix function can be used.

Find the published code on GitHub at /cybozu/eslint-config (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"
}

Supported editors

Most major editors such as Sublime Text (External link) and Visual Studio Code (External link) are supported. This article uses Visual Studio Code. Refer to the ESLint official website (External link) for a full list of supported editors.

Setting up ESLint (Windows)

Follow these steps to install ESLint and @cybozu/eslint-config on Windows. The following guide walks through the steps for global installation.

  1. Install ESLint with npm install -g eslint. Run the command to start the installation.

    1
    2
    
    npm init -y
    npm install -g eslint@8
  2. Install @cybozu/eslint-config with npm install -g @cybozu/eslint-config.

    1
    
    npm install -g @cybozu/eslint-config@23

    There will be warnings indicating that TypeScript and Prettier are not installed.
    Since this article does not use TypeScript nor Prettier, ignore these warnings. If needed, install them using the command below:

    1
    2
    3
    4
    
    # TypeScript
    npm install -g typescript
    # Prettier
    npm install -g prettier
  3. Enter npm ls -g --depth=0 to confirm that ESLint and @cybozu/eslint-config are installed.

    1
    2
    3
    4
    
    > npm ls -g --depth=0
    <installed folder>\npm
    +-- @cybozu/eslint-config@23.0.0
    +-- eslint@8.57.0
  4. Create a new file called .eslintrc.js with the following 3 lines in it. Make sure the file name starts with a "."

    1
    2
    3
    
    module.exports = {
      'extends': '@cybozu/eslint-config/presets/kintone-customize-es5'
    };
  5. Place the file .eslintrc.js in the parent folder of the folder that stores the source code to check with ESLint.

It is convenient to place the file in the folder C:\\Users\\_username_ etc. to execute ESLint with the same settings from any folder.

Setting up ESLint (Mac)

Follow these steps to install ESLint and @cybozu/eslint-config on Mac. The following guide walks through the steps for global installation.

  1. You may encounter permission errors when installing globally on Mac. Follow the workaround steps below to create a new directory and install it there.

    1. Create a directory called .npm-global with mkdir.

      1
      
      mkdir ~/.npm-global
    2. Run npm config set prefix to set the created directory as the installation destination.

      1
      
      npm config set prefix
    3. Create or open the file ~/.profile with the following command. Make sure the file name starts with a "."

      1
      
      vi ~/.profile
    4. The file will open in a vi editor. Write the following line in ~/.profile. export PATH updates the system environment variables.

      1
      
      export PATH=~/.npm-global/bin:$PATH

      Use the vi shortcuts to edit the file in the vi editor. For information on vi shortcuts, refer to the following link on the Red Hat website:
      An introduction to the vi editor (External link)

    5. Load the updated system environment variables with source ~/.profile

      1
      
      source ~/.profile
  2. Install ESLint with npm install -g eslint. Run the command to start the installation.

    1
    
    npm install -g eslint@8
  3. Install @cybozu/eslint-config with npm install -g @cybozu/eslint-config.

    1
    
    npm install -g @cybozu/eslint-config@23
  4. Enter npm ls -g --depth=0 to confirm that ESLint and @cybozu/eslint-config are installed.

    1
    2
    3
    4
    
    $ npm ls -g --depth=0
    <home directory> /.npm-global/lib
    ├── eslint@8.57.0
    └── @cybozu/eslint-config@23.0.0
  5. Create a new file .eslintrc.js with vi .eslintrc.js. Make sure the file name starts with a "."

    1
    
    vi .eslintrc.js
  6. Write the following 3 lines in ~/.eslintrc.js.

    1
    2
    3
    
    module.exports = {
      'extends': '@cybozu/eslint-config/presets/kintone-customize-es5'
    };

    Reference: How to operate the vi editor in the terminal.

    1. Switch vi to input mode by pressing the a key
    2. Enter the three lines above
    3. Switch vi back to command mode with the esc key
    4. Save changes and exit by entering :wq and then the enter key

Command line execution

Run ESLint with eslint _filename_ or eslint _foldername_.

For example, to run ESLint for a file called test.js, the command would look like the following:

1
> eslint test.js

▼ Sample code of test.js

1
2
3
4
5
6
7
(function() {
  'use strict'
  var func1 = function(a, b) {
    return a+ b;
  };
  var result = func1(1, 3);
})();

Note that the code above is created in a way to cause errors so to check that ESLint is working properly.

After running the command, the errors will be displayed as in the image below.

This sample code has the following warning/errors:

  • Missing semicolon
  • Operators must have spaces on both sides
  • 'result' is assigned a value but never used

No messages will be displayed if the file does not have any errors.

Fix errors that are found by ESLint. The JavaScript code may not work properly or may run with unintended behavior if not fixed. Warnings are strongly encouraged to be fixed, but are not required.

Refer to the Rules page on the ESLint official website (External link) for a detailed description of errors.

Integration with an editor

Follow the steps below to integrate ESLint with Visual Studio Code (VS Code).

  • Start VS Code and click on the Extensions icon.

  • Search for ESLint and click Install.

Restart VS Code when the installation has completed. The extension is enabled by restarting VS Code.

Result

ESLint validates any errors as it is entered and highlights the relevant part with a red, wavy underline.

A detailed description of the error is shown in the PROBLEMS tab.

Additional techniques for utilizing ESLint

Using the autofix feature

Adding the command line option --fix when executing automatically fixes the code where possible and updates the file. Note that some errors cannot be automatically fixed depending on the type of error.

Changing rule settings

To change rule settings, such as disabling a specific rule, edit .eslintrc.

  • Example 1: To disable jQuery object errors when using jQuery in a Kintone customization, add the globals key and set jQuery to readonly.
  • Example 2: To disable a specific rule, add the rules key and set the values of the settings to disable to off.

Below is a sample of .eslintrc that shows how examples 1 and 2 are coded.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
module.exports = {
  'extends': '@cybozu/eslint-config/presets/kintone-customize-es5',
  'globals': {
    'jQuery': 'readonly'
  },
  'rules': {
    'no-underscore-dangle': 'off',
    'no-console': 'off'
  }
};

Using various rule sets

The settings introduced in this article used a rule set that was created for those developers who customize Kintone with ES5 (ECMAScript5). @cybozu/eslint-config contains rules that can be used for other situations too. If needed, edit the .eslintrc.js file.

A few typical rule patterns will be introduced here. For all the rules, refer to the GitHub README (External link) .

General coding with ES2017
1
2
3
module.exports = {
  extends: '@cybozu'
};
Kintone customization with ES2017
1
2
3
module.exports = {
  extends: ['@cybozu', '@cybozu/eslint-config/globals/kintone']
};
General coding with Node.js
1
2
3
module.exports = {
  extends: '@cybozu/eslint-config/presets/node'
};
Kintone customization with Node.js
1
2
3
module.exports = {
  extends: ['@cybozu/eslint-config/presets/node', '@cybozu/eslint-config/globals/kintone']
};

Reference