2 title: Migrating to v2.0.0
7 ESLint v2.0.0 is the second major version release. As a result, there are some significant changes between how ESLint worked during its life in 0.x and 1.x and how it will work going forward. These changes are the direct result of feedback from the ESLint community of users and were not made without due consideration for the upgrade path. We believe that these changes make ESLint even better, and while some work is necessary to upgrade, we hope the pain of this upgrade is small enough that you will see the benefit of upgrading.
9 **Important:** If you are upgrading from 0.x, please refer to [Migrating to 1.0.0](./migrating-to-1.0.0) as your starting point.
11 ## Rule Schema Changes
13 Due to a quirk in the way rule schemas worked, it was possible that you'd need to account for the rule severity (0, 1, or 2) in a rule schema if the options were sufficiently complex. That would result in a schema such as:
23 "enum": ["always", "never"]
31 This was confusing to rule developers as it seemed that rules shouldn't be in charge of validating their own severity. In 2.0.0, rules no longer need to check their own severity.
33 **To address:** If you are exporting a rule schema that checks severity, you need to make several changes:
35 1. Remove the severity from the schema
36 1. Adjust `minItems` from 1 to 0
37 1. Adjust `maxItems` by subtracting 1
39 Here's what the schema from above looks like when properly converted:
46 "enum": ["always", "never"]
56 The following rules have been deprecated with new rules created to take their place. The following is a list of the removed rules and their replacements:
58 * [no-arrow-condition](https://eslint.org/docs/rules/no-arrow-condition) is replaced by a combination of [no-confusing-arrow](https://eslint.org/docs/rules/no-confusing-arrow) and [no-constant-condition](https://eslint.org/docs/rules/no-constant-condition). Turn on both of these rules to get the same functionality as `no-arrow-condition`.
59 * [no-empty-label](https://eslint.org/docs/rules/no-empty-label) is replaced by [no-labels](https://eslint.org/docs/rules/no-labels) with `{"allowLoop": true, "allowSwitch": true}` option.
60 * [space-after-keywords](https://eslint.org/docs/rules/space-after-keywords) is replaced by [keyword-spacing](https://eslint.org/docs/rules/keyword-spacing).
61 * [space-before-keywords](https://eslint.org/docs/rules/space-before-keywords) is replaced by [keyword-spacing](https://eslint.org/docs/rules/keyword-spacing).
62 * [space-return-throw-case](https://eslint.org/docs/rules/space-return-throw-case) is replaced by [keyword-spacing](https://eslint.org/docs/rules/keyword-spacing).
64 **To address:** You'll need to update your rule configurations to use the new rules. ESLint v2.0.0 will also warn you when you're using a rule that has been removed and will suggest the replacement rules. Hopefully, this will result in few surprises during the upgrade process.
66 ## Configuration Cascading Changes
68 Prior to 2.0.0, if a directory contained both an `.eslintrc` file and a `package.json` file with ESLint configuration information, the settings from the two files would be merged together. In 2.0.0, only the settings from the `.eslintrc.*` file are used and the ones in `package.json` are ignored when both are present. Otherwise, `package.json` can still be used with ESLint configuration, but only if no other `.eslintrc.*` files are present.
70 **To address:** If you have both an `.eslintrc.*` and `package.json` with ESLint configuration information in the same directory, combine your configurations into just one of those files.
72 ## Built-In Global Variables
74 Prior to 2.0.0, new global variables that were standardized as part of ES6 such as `Promise`, `Map`, `Set`, and `Symbol` were included in the built-in global environment. This could lead to potential issues when, for example, `no-undef` permitted use of the `Promise` constructor even in ES5 code where promises are unavailable. In 2.0.0, the built-in environment only includes the standard ES5 global variables, and the new ES6 global variables have been moved to the `es6` environment.
76 **To address:** If you are writing ES6 code, enable the `es6` environment if you have not already done so:
86 // Or in a configuration comment
92 Prior to 2.0.0, the way to enable language options was by using `ecmaFeatures` in your configuration. In 2.0.0:
94 * The `ecmaFeatures` property is now under a top-level `parserOptions` property.
95 * All ECMAScript 6 `ecmaFeatures` flags have been removed in favor of a `ecmaVersion` property under `parserOptions` that can be set to 3, 5 (default), or 6.
96 * The `ecmaFeatures.modules` flag has been replaced by a `sourceType` property under `parserOptions` which can be set to `"script"` (default) or `"module"` for ES6 modules.
98 **To address:** If you are using any ECMAScript 6 feature flags in `ecmaFeatures`, you'll need to use `ecmaVersion: 6` instead. The ECMAScript 6 feature flags are:
100 * `arrowFunctions` - enable [arrow functions](https://leanpub.com/understandinges6/read#leanpub-auto-arrow-functions)
101 * `binaryLiterals` - enable [binary literals](https://leanpub.com/understandinges6/read#leanpub-auto-octal-and-binary-literals)
102 * `blockBindings` - enable `let` and `const` (aka [block bindings](https://leanpub.com/understandinges6/read#leanpub-auto-block-bindings))
103 * `classes` - enable classes
104 * `defaultParams` - enable [default function parameters](https://leanpub.com/understandinges6/read/#leanpub-auto-default-parameters)
105 * `destructuring` - enable [destructuring](https://leanpub.com/understandinges6/read#leanpub-auto-destructuring-assignment)
106 * `forOf` - enable [`for-of` loops](https://leanpub.com/understandinges6/read#leanpub-auto-iterables-and-for-of)
107 * `generators` - enable [generators](https://leanpub.com/understandinges6/read#leanpub-auto-generators)
108 * `modules` - enable modules and global strict mode
109 * `objectLiteralComputedProperties` - enable [computed object literal property names](https://leanpub.com/understandinges6/read#leanpub-auto-computed-property-names)
110 * `objectLiteralDuplicateProperties` - enable [duplicate object literal properties](https://leanpub.com/understandinges6/read#leanpub-auto-duplicate-object-literal-properties) in strict mode
111 * `objectLiteralShorthandMethods` - enable [object literal shorthand methods](https://leanpub.com/understandinges6/read#leanpub-auto-method-initializer-shorthand)
112 * `objectLiteralShorthandProperties` - enable [object literal shorthand properties](https://leanpub.com/understandinges6/read#leanpub-auto-property-initializer-shorthand)
113 * `octalLiterals` - enable [octal literals](https://leanpub.com/understandinges6/read#leanpub-auto-octal-and-binary-literals)
114 * `regexUFlag` - enable the [regular expression `u` flag](https://leanpub.com/understandinges6/read#leanpub-auto-the-regular-expression-u-flag)
115 * `regexYFlag` - enable the [regular expression `y` flag](https://leanpub.com/understandinges6/read#leanpub-auto-the-regular-expression-y-flag)
116 * `restParams` - enable the [rest parameters](https://leanpub.com/understandinges6/read#leanpub-auto-rest-parameters)
117 * `spread` - enable the [spread operator](https://leanpub.com/understandinges6/read#leanpub-auto-the-spread-operator) for arrays
118 * `superInFunctions` - enable `super` references inside of functions
119 * `templateStrings` - enable [template strings](https://leanpub.com/understandinges6/read/#leanpub-auto-template-strings)
120 * `unicodeCodePointEscapes` - enable [code point escapes](https://leanpub.com/understandinges6/read/#leanpub-auto-escaping-non-bmp-characters)
122 If you're using any of these flags, such as:
132 Then you should enable ES6 using `ecmaVersion`:
142 If you're using any non-ES6 flags in `ecmaFeatures`, you need to move those inside of `parserOptions`. For instance:
152 Then you should move `ecmaFeatures` under `parserOptions`:
164 If you were using `ecmaFeatures.modules` to enable ES6 module support like this:
182 Additionally, if you are using `context.ecmaFeatures` inside of your rules, then you'll need to update your code in the following ways:
184 1. If you're using an ES6 feature flag such as `context.ecmaFeatures.blockBindings`, rewrite to check for `context.parserOptions.ecmaVersion > 5`.
185 1. If you're using `context.ecmaFeatures.modules`, rewrite to check that the `sourceType` property of the Program node is `"module"`.
186 1. If you're using a non-ES6 feature flag such as `context.ecmaFeatures.jsx`, rewrite to check for `context.parserOptions.ecmaFeatures.jsx`.
188 If you have a plugin with rules and you are using RuleTester, then you also need to update the options you pass for rules that use `ecmaFeatures`. For example:
191 var ruleTester = new RuleTester();
192 ruleTester.run("no-var", rule, {
196 parserOptions: { ecmaVersion: 6 }
202 If you're not using `ecmaFeatures` in your configuration or your custom/plugin rules and tests, then no change is needed.
204 ## New Rules in `"eslint:recommended"`
208 "extends": "eslint:recommended"
212 In 2.0.0, the following 11 rules were added to `"eslint:recommended"`.
214 * [constructor-super](https://eslint.org/docs/rules/constructor-super)
215 * [no-case-declarations](https://eslint.org/docs/rules/no-case-declarations)
216 * [no-class-assign](https://eslint.org/docs/rules/no-class-assign)
217 * [no-const-assign](https://eslint.org/docs/rules/no-const-assign)
218 * [no-dupe-class-members](https://eslint.org/docs/rules/no-dupe-class-members)
219 * [no-empty-pattern](https://eslint.org/docs/rules/no-empty-pattern)
220 * [no-new-symbol](https://eslint.org/docs/rules/no-new-symbol)
221 * [no-self-assign](https://eslint.org/docs/rules/no-self-assign)
222 * [no-this-before-super](https://eslint.org/docs/rules/no-this-before-super)
223 * [no-unexpected-multiline](https://eslint.org/docs/rules/no-unexpected-multiline)
224 * [no-unused-labels](https://eslint.org/docs/rules/no-unused-labels)
226 **To address:** If you don't want to be notified by those rules, you can simply disable those rules.
230 "extends": "eslint:recommended",
232 "no-case-declarations": 0,
233 "no-class-assign": 0,
234 "no-const-assign": 0,
235 "no-dupe-class-members": 0,
236 "no-empty-pattern": 0,
239 "no-this-before-super": 0,
240 "no-unexpected-multiline": 0,
241 "no-unused-labels": 0,
242 "constructor-super": 0
247 ## Scope Analysis Changes
249 We found some bugs in our scope analysis that needed to be addressed. Specifically, we were not properly accounting for global variables in all the ways they are defined.
251 Originally, `Variable` objects and `Reference` objects refer each other:
253 * `Variable#references` property is an array of `Reference` objects which are referencing the variable.
254 * `Reference#resolved` property is a `Variable` object which are referenced.
256 But until 1.x, the following variables and references had the wrong value (empty) in those properties:
258 * `var` declarations in the global.
259 * `function` declarations in the global.
260 * Variables defined in config files.
261 * Variables defined in `/* global */` comments.
263 Now, those variables and references have correct values in these properties.
265 `Scope#through` property has references where `Reference#resolved` is `null`. So as a result of this change, the value of `Scope#through` property was changed also.
267 **To address:** If you are using `Scope#through` to find references of a built-in global variable, you need to make several changes.
269 For example, this is how you might locate the `window` global variable in 1.x:
272 var globalScope = context.getScope();
273 globalScope.through.forEach(function(reference) {
274 if (reference.identifier.name === "window") {
275 checkForWindow(reference);
280 This was a roundabout way to find the variable because it was added after the fact by ESLint. The `window` variable was in `Scope#through` because the definition couldn't be found.
282 In 2.0.0, `window` is no longer located in `Scope#through` because we have added back the correct declaration. That means you can reference the `window` object (or any other global object) directly. So the previous example would change to this:
285 var globalScope = context.getScope();
286 var variable = globalScope.set.get("window");
288 variable.references.forEach(checkForWindow);
292 Further Reading: <https://estools.github.io/escope/>
294 ## Default Changes When Using `eslint:recommended`
296 This will affect you if you are extending from `eslint:recommended`, and are enabling [`no-multiple-empty-lines`] or [`func-style`] with only a severity, such as:
300 "extends": "eslint:recommended",
302 "no-multiple-empty-lines": 2,
308 The rule `no-multiple-empty-lines` has no default exceptions, but in ESLint `1.x`, a default from `eslint:recommended` was applied such that a maximum of two empty lines would be permitted.
310 The rule `func-style` has a default configuration of `"expression"`, but in ESLint `1.x`, `eslint:recommended` defaulted it to `"declaration"`.
312 ESLint 2.0.0 removes these conflicting defaults, and so you may begin seeing linting errors related to these rules.
314 **To address:** If you would like to maintain the previous behavior, update your configuration for `no-multiple-empty-lines` by adding `{"max": 2}`, and change `func-style` to `"declaration"`. For example:
318 "extends": "eslint:recommended",
320 "no-multiple-empty-lines": [2, {"max": 2}],
321 "func-style": [2, "declaration"]
326 [`no-multiple-empty-lines`]: ../rules/no-multiple-empty-lines
327 [`func-style`]: ../rules/func-style
329 ## SourceCode constructor (Node API) changes
331 `SourceCode` constructor got to handle Unicode BOM.
332 If the first argument `text` has BOM, `SourceCode` constructor sets `true` to `this.hasBOM` and strips BOM from the text.
335 var SourceCode = require("eslint").SourceCode;
337 var code = new SourceCode("\uFEFFvar foo = bar;", ast);
339 assert(code.hasBOM === true);
340 assert(code.text === "var foo = bar;");
343 So the second argument `ast` also should be parsed from stripped text.
345 **To address:** If you are using `SourceCode` constructor in your code, please parse the source code after it stripped BOM:
348 var ast = yourParser.parse(text.replace(/^\uFEFF/, ""), options);
349 var sourceCode = new SourceCode(text, ast);
354 * [`strict`](../rules/strict) - defaults to `"safe"` (previous default was `"function"`)
356 ## Plugins No Longer Have Default Configurations
358 Prior to v2.0.0, plugins could specify a `rulesConfig` for the plugin. The `rulesConfig` would automatically be applied whenever someone uses the plugin, which is the opposite of what ESLint does in every other situation (where nothing is on by default). To bring plugins behavior in line, we have removed support for `rulesConfig` in plugins.
360 **To address:** If you are using a plugin in your configuration file, you will need to manually enable the plugin rules in the configuration file.