eslint/docs/user-guide/migrating-from-jscs.md

   1 # Migrating from JSCS
   2
   3 In April 2016, we [announced](https://eslint.org/blog/2016/04/welcoming-jscs-to-eslint) that the JSCS project was shutting down and the JSCS team would be joining the ESLint team. This guide is intended to help those who are using JSCS to migrate their settings and projects to use ESLint. We've tried to automate as much of the conversion as possible, but there are some manual changes that are needed.
   4
   5 ## Terminology
   6
   7 Before beginning the process of migrating to ESLint, it's helpful to understand some of the terminology that ESLint uses and how it relates to terminology that JSCS uses.
   8
   9 * **Configuration File** - In JSCS, the configuration file is `.jscsrc`, `.jscsrc.json`, `.jscsrc.yaml`, or `.jscsrs.js`. In ESLint, the configuration file can be `.eslintrc.json`, `.eslintrc.yml`, `.eslintrc.yaml`, or `.eslintrc.js` (there is also a deprecated `.eslintrc` file format).
  10 * **Presets** - In JSCS, there were numerous predefined configurations shipped directly within JSCS. ESLint ships with just one predefined configuration (`eslint:recommended`) that has no style rules enabled. However, ESLint does support [shareable configs](https://eslint.org/docs/developer-guide/shareable-configs). Shareable configs are configurations that are published on their own to npm and there are shareable configs available for almost all of the JSCS presets (see the "Converting Presets" section below). Additionally, the "preset" option in a configuration file is the equivalent of the ESLint "extends" option.
  11
  12 ## Convert Configuration Files Using Polyjuice
  13
  14 [Polyjuice](https://github.com/brenolf/polyjuice) is a utility for converting JSCS (and JSHint) configuration files into ESLint configuration files automatically. It understands the equivalent rules from each utility and will automatically output an ESLint configuration file that is a good approximation of your existing JSCS file.
  15
  16 To install Polyjuice:
  17
  18 ```sh
  19 $ npm install -g polyjuice
  20 ```
  21
  22 Polyjuice works with JSON configuration files, so if you're using a JavaScript or YAML JSCS configuration file, you should first convert it into a JSON configuration file.
  23
  24 To convert your configuration file, pass in the location of your `.jscs.json` file using the `--jscs` flag:
  25
  26 ```sh
  27 $ polyjuice --jscs .jscsrc.json > .eslintrc.json
  28 ```
  29
  30 This creates a `.eslintrc.json` with the equivalent rules from `.jscsrc.json`.
  31
  32 If you have multiple `.jscsrc.json` files, you can pass them all and Polyjuice will combine them into one `.eslintrc.json` file:
  33
  34 ```sh
  35 $ polyjuice --jscs .jscsrc.json ./foo/.jscsrc.json > .eslintrc.json
  36 ```
  37
  38 **Note:** Polyjuice does a good job of creating a reasonable ESLint configuration from your JSCS configuration, but it may not be 100%. You may still see different warnings than you saw with JSCS, and so you may need to further modify your configuration after using Polyjuice. This is especially true if you're using inline comments to enable/disable certain rules in JSCS (you'll need to manually convert those to use ESLint-style comments instead, see "Disabling Rules Inline" later in this page).
  39
  40 ### Creating a New Configuration From Scratch
  41
  42 If you don't want to convert your JSCS configuration directly into an ESLint configuration, then you can use ESLint's built-in wizard to get you started. Just run:
  43
  44 ```sh
  45 $ eslint --init
  46 ```
  47
  48 You'll be guided through a series of questions that will help you setup a basic configuration file to get you started.
  49
  50 ## Converting Presets
  51
  52 There are shareable configs available for most JSCS presets. The equivalent shareable configs for each JSCS preset are listed in the following table:
  53
  54 | **JSCS Preset** | **ESLint Shareable Config** |
  55 |-----------------|-----------------------------|
  56 | `airbnb`        | [`eslint-config-airbnb-base`](https://github.com/airbnb/javascript/tree/master/packages/eslint-config-airbnb-base) |
  57 | `crockford`        | (not available) |
  58 | `google`        | [`eslint-config-google`](https://github.com/google/eslint-config-google) |
  59 | `grunt`        | [`eslint-config-grunt`](https://github.com/markelog/eslint-config-grunt) |
  60 | `idiomatic`        | [`eslint-config-idiomatic`](https://github.com/jamespamplin/eslint-config-idiomatic) |
  61 | `jquery`        | [`eslint-config-jquery`](https://github.com/jquery/eslint-config-jquery) |
  62 | `mdcs`        | [`eslint-config-mdcs`](https://github.com/zz85/mrdoobapproves) |
  63 | `node-style-guide`        | [`eslint-config-node-style-guide`](https://github.com/pdehaan/eslint-config-node-style-guide) |
  64 | `wikimedia`        | [`eslint-config-wikimedia`](https://github.com/wikimedia/eslint-config-wikimedia) |
  65 | `wordpress`        | [`eslint-config-wordpress`](https://github.com/WordPress-Coding-Standards/eslint-config-wordpress) |
  66
  67 As an example, suppose that you are using the `airbnb` preset, so your `.jscsrc` file looks like this:
  68
  69 ```json
  70 {
  71     "preset": "airbnb"
  72 }
  73 ```
  74
  75 In order to get the same functionality in ESLint, you would first need to install the `eslint-config-airbnb` shareable config package:
  76
  77 ```sh
  78 $ npm install eslint-config-airbnb-base --save-dev
  79 ```
  80
  81 And then you would modify your configuration file like this:
  82
  83 ```json
  84 {
  85     "extends": "airbnb-base"
  86 }
  87 ```
  88
  89 ESLint sees `"airbnb-base"` and will look for `eslint-config-airbnb-base` (to save you some typing).
  90
  91 ## Disabling Rules Inline
  92
  93 Both JSCS and ESLint use comments inside of files to disable rules around certain parts of your code. The following table lists out the JSCS inline configuration comments and their ESLint equivalents.
  94
  95 | **Description** | **JSCS Comment** | **ESLint Comment** |
  96 |-----------------|------------------|--------------------|
  97 | Disable all rules | `// jscs:disable` or `/* jscs:disable */` | `/* eslint-disable */` |
  98 | Enable all rules | `// jscs:enable` or `/* jscs:enable */` | `/* eslint-enable */` |
  99 | Disable one rule | `// jscs:disable ruleName` or `/* jscs:disable ruleName */` | `/* eslint-disable rule-name */` |
 100 | Enable one rule | `// jscs:enable ruleName` or `/* jscs:enable ruleName */` | `/* eslint-enable rule-name */` |
 101 | Disable multiple rules | `// jscs:disable ruleName1, ruleName2` or `/* jscs:disable ruleName1, ruleName2 */` | `/* eslint-disable rule-name1, rule-name2 */` |
 102 | Enable multiple rules | `// jscs:enable ruleName1, ruleName2` or `/* jscs:enable ruleName1, ruleName2 */` | `/* eslint-enable rule-name1, rule-name2 */` |
 103 | Disable one rule on single line | `// jscs:ignore ruleName` | `// eslint-disable-line rule-name` |
 104
 105 ## Command Line Options
 106
 107 Both JSCS and ESLint have command line arguments corresponding to many of their configuration options. The following are the ESLint equivalents of JSCS command line options.
 108
 109 ### `--fix`
 110
 111 JSCS uses the `--fix` option to apply automatic fixes to code:
 112
 113 ```sh
 114 $ jscs --fix file.js
 115 ```
 116
 117 ESLint has the same option:
 118
 119 ```sh
 120 $ eslint --fix file.js
 121 ```
 122
 123 ### `--auto-configure`
 124
 125 The JSCS `--auto-configure` option created a configuration based on what it found in a given file:
 126
 127 ```sh
 128 $ jscs --auto-configure file.js
 129 ```
 130
 131 In ESLint, there's a similar option when you use `--init`. Just select "Inspect your JavaScript file(s)":
 132
 133 ```sh
 134 $ eslint --init
 135 ? How would you like to configure ESLint? (Use arrow keys)
 136 > Answer questions about your style
 137   Use a popular style guide
 138   Inspect your JavaScript file(s)
 139 ```
 140
 141 ## `--config`, `-c`
 142
 143 JSCS allows you to specify a configuration file to use on the command line using either `--config` or `-c`, such as:
 144
 145 ```sh
 146 $ jscs --config myconfig.json file.js
 147 $ jscs -c myconfig.json file.js
 148 ```
 149
 150 Both flags are also supported by ESLint:
 151
 152 ```sh
 153 $ eslint --config myconfig.json file.js
 154 $ eslint -c myconfig.json file.js
 155 ```
 156
 157 ## Piping Code Into ESLint
 158
 159 In JSCS, you can pipe code in like this:
 160
 161 ```sh
 162 $ cat file.js | jscs
 163 ```
 164
 165 In ESLint, you can also pipe in code, but you need to use the `--stdin` flag:
 166
 167 ```sh
 168 $ cat file.js | eslint --stdin
 169 ```