Linting your TypeScript Codebase

Whether you're adding linting to a new TypeScript codebase, adding TypeScript to an old codebase, or migrating from the deprecated TSLint, the steps aren't a whole lot different.

Installation

First step is to make sure you've got the required packages installed:

npm

npm install --save-dev eslint typescript @typescript-eslint/parser @typescript-eslint/eslint-plugin

Yarn

yarn add --dev eslint typescript @typescript-eslint/parser @typescript-eslint/eslint-plugin

Configuration

Next, create a .eslintrc.js config file in the root of your project, and populate it with the following:

.eslintrc.js

module.exports = {
  root: true,
  parser: '@typescript-eslint/parser',
  plugins: [
    '@typescript-eslint',
  ],
  extends: [
    'eslint:recommended',
    'plugin:@typescript-eslint/recommended',
  ],
};

This is about the smallest config file we recommend. There's a lot more you can add to this as you further onboard, but this will be enough to get you started.

Details

Explaining the important bits:

• parser: '@typescript-eslint/parser' tells ESLint to use the parser package you installed (@typescript-eslint/parser).
  • This allows ESLint to understand TypeScript syntax.
  • This is required, or else ESLint will throw errors as it tries to parse TypeScript code as if it were regular JavaScript.
• plugins: ['@typescript-eslint'] tells ESLint to load the plugin package you installed (@typescript-eslint/eslint-plugin).
  • This allows you to use the rules within your codebase.
• extends: [ ... ] tells ESLint that your config extends the given configurations.
  • eslint:recommended is ESLint's inbuilt "recommended" config - it turns on a small, sensible set of rules which lint for well-known best-practices.
  • plugin:@typescript-eslint/recommended is our "recommended" config - it's just like eslint:recommended, except it only turns on rules from our TypeScript-specific plugin.

Ignoring unnecessary files

Next, create a .eslintignore file in the root of your project. This file will tell ESLint which files and folders it should never lint.

Add the following lines to the file:

.eslintignore

# don't ever lint node_modules
node_modules
# don't lint build output (make sure it's set to your correct build folder name)
dist

Further Configuration Documentation

• You can read more about configuring ESLint in their documentation on configuration.
• You can read more about the rules provided by ESLint in their documentation on their rules.
• You can read more about the rules provided by us in our plugin documentation.

Running ESLint

With that configured, open a terminal to the root of your project, and run the following command

npm

npm run eslint . --ext .js,.jsx,.ts,.tsx

Yarn

yarn run eslint . --ext .js,.jsx,.ts,.tsx

That's it - ESLint will lint all .js, .jsx, .ts, and .tsx files within the current folder, and will output the results to your terminal.

You can also get results in realtime inside most IDEs via a plugin - search your IDE's extension store.

Next Steps

With that configured you can now start to delve into the wide and extensive ESLint ecosystem of plugins and configs.

Type-Aware Rules

We have a lot of awesome rules which utilize the power of TypeScript's type information. They require a little bit of extra setup beyond this first step, so visit the next page to see how to set this up.

Prettier

If you use prettier, there is also a helpful config to help ensure ESLint doesn't report on formatting issues that prettier will fix: eslint-config-prettier.

Using this config by adding it to the end of your extends:

.eslintrc.js

  module.exports = {
    root: true,
    parser: '@typescript-eslint/parser',
    plugins: [
      '@typescript-eslint',
    ],
    extends: [
      'eslint:recommended',
      'plugin:@typescript-eslint/recommended',
+     'prettier',
    ],
  };

Community Configs

Configurations exist solely to provide a comprehensive base config for you, with the intention that you add the config and it gives you an opinionated setup. Many configuration packages exist in the ESLint ecosystem. A few popular all-in-one configs are:

• Airbnb's ESLint config: eslint-config-airbnb-typescript.
• Standard: eslint-config-standard-with-typescript.

To use one of these complete config packages, you would replace the extends with the package name. For example:

.eslintrc.js

  module.exports = {
    root: true,
    parser: '@typescript-eslint/parser',
    plugins: [
      '@typescript-eslint',
    ],
    extends: [
-     'eslint:recommended',
-     'plugin:@typescript-eslint/recommended',
+     'airbnb-typescript',
    ],
  };

Search "eslint-config" on npm for more.

Plugins

ESLint plugins provide additional rules and other functionality on top of ESLint. Below are just a few examples:

• ESLint comment restrictions: eslint-plugin-eslint-comments
• Import/export conventions : eslint-plugin-import
• Jest testing: eslint-plugin-jest
• NodeJS best practices: eslint-plugin-node
• React best practices: eslint-plugin-react and eslint-plugin-react-hooks

Every plugin that is out there includes documentation on the various configurations and rules they offer. A typical plugin might be used like:

.eslintrc.js

  module.exports = {
    root: true,
    parser: '@typescript-eslint/parser',
    plugins: [
      '@typescript-eslint',
+     'jest',
    ],
    extends: [
      'eslint:recommended',
      'plugin:@typescript-eslint/recommended',
+     'plugin:jest/recommended',
    ],
  };

Search "eslint-plugin" on npm for more.

Troubleshooting

If you're having problems getting this working, please have a look at our Troubleshooting FAQ.