Getting Started

These docs walk you through setting up ESLint, this plugin, and our parser. If you know what you're doing and just want to quick start, read on...

Quick-start

Installation

Make sure you have TypeScript and @typescript-eslint/parser installed:

$ yarn add -D typescript @typescript-eslint/parser
$ npm i --save-dev typescript @typescript-eslint/parser

Then install the plugin:

$ yarn add -D @typescript-eslint/eslint-plugin
$ npm i --save-dev @typescript-eslint/eslint-plugin

It is important that you use the same version number for @typescript-eslint/parser and @typescript-eslint/eslint-plugin.

Note: If you installed ESLint globally (using the -g flag) then you must also install @typescript-eslint/eslint-plugin globally.

Usage

Add @typescript-eslint/parser to the parser field and @typescript-eslint to the plugins section of your .eslintrc configuration file, then configure the rules you want to use under the rules section.

{
  "parser": "@typescript-eslint/parser",
  "plugins": ["@typescript-eslint"],
  "rules": {
    "@typescript-eslint/rule-name": "error"
  }
}

You can also enable all the recommended rules for our plugin. Add plugin:@typescript-eslint/recommended in extends:

{
  "extends": ["plugin:@typescript-eslint/recommended"]
}

Note: Make sure to use eslint --ext .js,.ts since by default eslint will only search for .js files.

Recommended Configs

You can also use eslint:recommended (the set of rules which are recommended for all projects by the ESLint Team) with this plugin:

{
  "extends": ["eslint:recommended", "plugin:@typescript-eslint/recommended"]
}

As of version 2 of this plugin, by design, none of the rules in the main recommended config require type-checking in order to run. This means that they are more lightweight and faster to run.

Some highly valuable rules simply require type-checking in order to be implemented correctly, however, so we provide an additional config you can extend from called recommended-requiring-type-checking. You would apply this in addition to the recommended configs previously mentioned, e.g.:

{
  "extends": [
    "eslint:recommended",
    "plugin:@typescript-eslint/recommended",
    "plugin:@typescript-eslint/recommended-requiring-type-checking"
  ]
}

Pro Tip: For larger codebases you may want to consider splitting our linting into two separate stages: 1. fast feedback rules which operate purely based on syntax (no type-checking), 2. rules which are based on semantics (type-checking).

You can read more about linting with type information here

Supported Rules

Key: :heavy_check_mark: = recommended, :wrench: = fixable, :thought_balloon: = requires type information

NameDescription:heavy_check_mark::wrench::thought_balloon:
@typescript-eslint/adjacent-overload-signaturesRequire that member overloads be consecutive:heavy_check_mark:
@typescript-eslint/array-typeRequires using either T[] or Array<T> for arrays:wrench:
@typescript-eslint/await-thenableDisallows awaiting a value that is not a Thenable:heavy_check_mark::thought_balloon:
@typescript-eslint/ban-ts-commentBans // @ts-<directive> comments from being used or requires descriptions after directive:heavy_check_mark:
@typescript-eslint/ban-tslint-commentBans // tslint:<rule-flag> comments from being used:wrench:
@typescript-eslint/ban-typesBans specific types from being used:heavy_check_mark::wrench:
@typescript-eslint/class-literal-property-styleEnsures that literals on classes are exposed in a consistent style:wrench:
@typescript-eslint/consistent-type-assertionsEnforces consistent usage of type assertions
@typescript-eslint/consistent-type-definitionsConsistent with type definition either interface or type:wrench:
@typescript-eslint/consistent-type-importsEnforces consistent usage of type imports:wrench:
@typescript-eslint/explicit-function-return-typeRequire explicit return types on functions and class methods
@typescript-eslint/explicit-member-accessibilityRequire explicit accessibility modifiers on class properties and methods:wrench:
@typescript-eslint/explicit-module-boundary-typesRequire explicit return and argument types on exported functions' and classes' public class methods:heavy_check_mark:
@typescript-eslint/member-delimiter-styleRequire a specific member delimiter style for interfaces and type literals:wrench:
@typescript-eslint/member-orderingRequire a consistent member declaration order
@typescript-eslint/method-signature-styleEnforces using a particular method signature syntax.:wrench:
@typescript-eslint/naming-conventionEnforces naming conventions for everything across a codebase:thought_balloon:
@typescript-eslint/no-base-to-stringRequires that .toString() is only called on objects which provide useful information when stringified:thought_balloon:
@typescript-eslint/no-confusing-non-null-assertionDisallow non-null assertion in locations that may be confusing:wrench:
@typescript-eslint/no-dynamic-deleteDisallow the delete operator with computed key expressions:wrench:
@typescript-eslint/no-empty-interfaceDisallow the declaration of empty interfaces:heavy_check_mark::wrench:
@typescript-eslint/no-explicit-anyDisallow usage of the any type:heavy_check_mark::wrench:
@typescript-eslint/no-extra-non-null-assertionDisallow extra non-null assertion:heavy_check_mark::wrench:
@typescript-eslint/no-extraneous-classForbids the use of classes as namespaces
@typescript-eslint/no-floating-promisesRequires Promise-like values to be handled appropriately:heavy_check_mark::thought_balloon:
@typescript-eslint/no-for-in-arrayDisallow iterating over an array with a for-in loop:heavy_check_mark::thought_balloon:
@typescript-eslint/no-implicit-any-catchDisallow usage of the implicit any type in catch clauses:wrench:
@typescript-eslint/no-implied-evalDisallow the use of eval()-like methods:heavy_check_mark::thought_balloon:
@typescript-eslint/no-inferrable-typesDisallows explicit type declarations for variables or parameters initialized to a number, string, or boolean:heavy_check_mark::wrench:
@typescript-eslint/no-invalid-void-typeDisallows usage of void type outside of generic or return types
@typescript-eslint/no-misused-newEnforce valid definition of new and constructor:heavy_check_mark:
@typescript-eslint/no-misused-promisesAvoid using promises in places not designed to handle them:heavy_check_mark::thought_balloon:
@typescript-eslint/no-namespaceDisallow the use of custom TypeScript modules and namespaces:heavy_check_mark:
@typescript-eslint/no-non-null-asserted-optional-chainDisallows using a non-null assertion after an optional chain expression:heavy_check_mark:
@typescript-eslint/no-non-null-assertionDisallows non-null assertions using the ! postfix operator:heavy_check_mark:
@typescript-eslint/no-parameter-propertiesDisallow the use of parameter properties in class constructors
@typescript-eslint/no-require-importsDisallows invocation of require()
@typescript-eslint/no-this-aliasDisallow aliasing this:heavy_check_mark:
@typescript-eslint/no-throw-literalDisallow throwing literals as exceptions:thought_balloon:
@typescript-eslint/no-type-aliasDisallow the use of type aliases
@typescript-eslint/no-unnecessary-boolean-literal-compareFlags unnecessary equality comparisons against boolean literals:wrench::thought_balloon:
@typescript-eslint/no-unnecessary-conditionPrevents conditionals where the type is always truthy or always falsy:wrench::thought_balloon:
@typescript-eslint/no-unnecessary-qualifierWarns when a namespace qualifier is unnecessary:wrench::thought_balloon:
@typescript-eslint/no-unnecessary-type-argumentsEnforces that type arguments will not be used if not required:wrench::thought_balloon:
@typescript-eslint/no-unnecessary-type-assertionWarns if a type assertion does not change the type of an expression:heavy_check_mark::wrench::thought_balloon:
@typescript-eslint/no-unsafe-assignmentDisallows assigning any to variables and properties:heavy_check_mark::thought_balloon:
@typescript-eslint/no-unsafe-callDisallows calling an any type value:heavy_check_mark::thought_balloon:
@typescript-eslint/no-unsafe-member-accessDisallows member access on any typed variables:heavy_check_mark::thought_balloon:
@typescript-eslint/no-unsafe-returnDisallows returning any from a function:heavy_check_mark::thought_balloon:
@typescript-eslint/no-var-requiresDisallows the use of require statements except in import statements:heavy_check_mark:
@typescript-eslint/prefer-as-constPrefer usage of as const over literal type:heavy_check_mark::wrench:
@typescript-eslint/prefer-enum-initializersPrefer initializing each enums member value
@typescript-eslint/prefer-for-ofPrefer a ‘for-of’ loop over a standard ‘for’ loop if the index is only used to access the array being iterated
@typescript-eslint/prefer-function-typeUse function types instead of interfaces with call signatures:wrench:
@typescript-eslint/prefer-includesEnforce includes method over indexOf method:wrench::thought_balloon:
@typescript-eslint/prefer-literal-enum-memberRequire that all enum members be literal values to prevent unintended enum member name shadow issues
@typescript-eslint/prefer-namespace-keywordRequire the use of the namespace keyword instead of the module keyword to declare custom TypeScript modules:heavy_check_mark::wrench:
@typescript-eslint/prefer-nullish-coalescingEnforce the usage of the nullish coalescing operator instead of logical chaining:thought_balloon:
@typescript-eslint/prefer-optional-chainPrefer using concise optional chain expressions instead of chained logical ands
@typescript-eslint/prefer-readonlyRequires that private members are marked as readonly if they're never modified outside of the constructor:wrench::thought_balloon:
@typescript-eslint/prefer-readonly-parameter-typesRequires that function parameters are typed as readonly to prevent accidental mutation of inputs:thought_balloon:
@typescript-eslint/prefer-reduce-type-parameterPrefer using type parameter when calling Array#reduce instead of casting:wrench::thought_balloon:
@typescript-eslint/prefer-regexp-execEnforce that RegExp#exec is used instead of String#match if no global flag is provided:heavy_check_mark::thought_balloon:
@typescript-eslint/prefer-string-starts-ends-withEnforce the use of String#startsWith and String#endsWith instead of other equivalent methods of checking substrings:wrench::thought_balloon:
@typescript-eslint/prefer-ts-expect-errorRecommends using @ts-expect-error over @ts-ignore:wrench:
@typescript-eslint/promise-function-asyncRequires any function or method that returns a Promise to be marked async:thought_balloon:
@typescript-eslint/require-array-sort-compareRequires Array#sort calls to always provide a compareFunction:thought_balloon:
@typescript-eslint/restrict-plus-operandsWhen adding two variables, operands must both be of type number or of type string:heavy_check_mark::thought_balloon:
@typescript-eslint/restrict-template-expressionsEnforce template literal expressions to be of string type:heavy_check_mark::thought_balloon:
@typescript-eslint/strict-boolean-expressionsRestricts the types allowed in boolean expressions:thought_balloon:
@typescript-eslint/switch-exhaustiveness-checkExhaustiveness checking in switch with union type:thought_balloon:
@typescript-eslint/triple-slash-referenceSets preference level for triple slash directives versus ES6-style import declarations:heavy_check_mark:
@typescript-eslint/type-annotation-spacingRequire consistent spacing around type annotations:wrench:
@typescript-eslint/typedefRequires type annotations to exist
@typescript-eslint/unbound-methodEnforces unbound methods are called with their expected scope:heavy_check_mark::thought_balloon:
@typescript-eslint/unified-signaturesWarns for any two overloads that could be unified into one by using a union or an optional/rest parameter

Extension Rules

In some cases, ESLint provides a rule itself, but it doesn't support TypeScript syntax; either it crashes, or it ignores the syntax, or it falsely reports against it. In these cases, we create what we call an extension rule; a rule within our plugin that has the same functionality, but also supports TypeScript.

Key: :heavy_check_mark: = recommended, :wrench: = fixable, :thought_balloon: = requires type information

NameDescription:heavy_check_mark::wrench::thought_balloon:
@typescript-eslint/brace-styleEnforce consistent brace style for blocks:wrench:
@typescript-eslint/comma-dangleRequire or disallow trailing comma:wrench:
@typescript-eslint/comma-spacingEnforces consistent spacing before and after commas:wrench:
@typescript-eslint/default-param-lastEnforce default parameters to be last
@typescript-eslint/dot-notationenforce dot notation whenever possible:wrench::thought_balloon:
@typescript-eslint/func-call-spacingRequire or disallow spacing between function identifiers and their invocations:wrench:
@typescript-eslint/indentEnforce consistent indentation:wrench:
@typescript-eslint/init-declarationsrequire or disallow initialization in variable declarations
@typescript-eslint/keyword-spacingEnforce consistent spacing before and after keywords:wrench:
@typescript-eslint/lines-between-class-membersRequire or disallow an empty line between class members:wrench:
@typescript-eslint/no-array-constructorDisallow generic Array constructors:heavy_check_mark::wrench:
@typescript-eslint/no-dupe-class-membersDisallow duplicate class members
@typescript-eslint/no-empty-functionDisallow empty functions:heavy_check_mark:
@typescript-eslint/no-extra-parensDisallow unnecessary parentheses:wrench:
@typescript-eslint/no-extra-semiDisallow unnecessary semicolons:heavy_check_mark::wrench:
@typescript-eslint/no-invalid-thisdisallow this keywords outside of classes or class-like objects
@typescript-eslint/no-loop-funcDisallow function declarations that contain unsafe references inside loop statements
@typescript-eslint/no-loss-of-precisionDisallow literal numbers that lose precision
@typescript-eslint/no-magic-numbersDisallow magic numbers
@typescript-eslint/no-redeclareDisallow variable redeclaration
@typescript-eslint/no-shadowDisallow variable declarations from shadowing variables declared in the outer scope
@typescript-eslint/no-unused-expressionsDisallow unused expressions
@typescript-eslint/no-unused-varsDisallow unused variables:heavy_check_mark:
@typescript-eslint/no-use-before-defineDisallow the use of variables before they are defined
@typescript-eslint/no-useless-constructorDisallow unnecessary constructors
@typescript-eslint/quotesEnforce the consistent use of either backticks, double, or single quotes:wrench:
@typescript-eslint/require-awaitDisallow async functions which have no await expression:heavy_check_mark::thought_balloon:
@typescript-eslint/return-awaitEnforces consistent returning of awaited values:wrench::thought_balloon:
@typescript-eslint/semiRequire or disallow semicolons instead of ASI:wrench:
@typescript-eslint/space-before-function-parenEnforces consistent spacing before function parenthesis:wrench:

Contributing

See the contributing guide here.