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)

Supported editors

Most major editors such as Sublime Text (External link), Atom (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. Check the node.js version with node -v in the command prompt. Update node.js if the version is older than 6.14. If node.js is not yet installed, visit the node.js website (External link) and install node.js first.

    1
    2
    
    > node -v
    v8.9.4
    
  2. Install ESLint with npm install -g eslint. Run the command to start the installation.

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

    1
    
    > npm install -g @cybozu/eslint-config
    
  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
    <installed folder>\npm
    +-- @cybozu/eslint-config@3.0.2
    +-- eslint@5.10.0
    
  5. 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'
    };
    
  6. Place the file .eslintrc.js in the parent folder of the folder that stores the source code to check with ESLint.

    Image: A file directory showing the .eslintrc.js file being placed in the parent folder that stores the source code.

    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. Check the installed version of Node.js with node -v in the terminal. Update Node.js if the version is older than 6.14.

    1
    2
    
    $ node -v
    v8.9.4
    
  2. You may encounter permission errors when installing globally on Mac. Follow the workaround steps below to create a new directory and install it in 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 vi ~/.profile. Make sure the file name starts with a “.”

      1
      
      vi ~/.profile
      
    4. Write the following line in ~/.profile. export PATH updates the system environment variables.

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

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

      1. Switch vi to input mode by entering the a key
      2. Enter the line in step 2-4
      3. Switch vi back to command mode with the esc key
      4. Save changes and exit by entering :wq and then the enter key
    5. Load the updated system environment variables with source ~/.profile

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

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

    1
    
    npm install -g @cybozu/eslint-config
    
  5. 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@4.19.0
    └── @cybozu/eslint-config@1.2.0
    
  6. Create a new file .eslintrc.js with vi .eslintrc.js. Make sure the file name starts with a “.”

    1
    
    vi .eslintrc.js
    
  7. 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.

Screenshot: Errors are displayed in the console after running the command.

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 unintedned 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.

    Screenshot: Users clicks on the Extensions icon.

  • Search for ESLint and click Install.

    Screenshot: Users searches 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 .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 patters 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