Skip to main content

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 install --save-dev eslint typescript @typescript-eslint/parser @typescript-eslint/eslint-plugin

Configuration​

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

.eslintrc.cjs
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.

info

The .cjs extension will explicitly set the file to a CommonJS module, in case your project has "type": "module" in its package.json.

If your project doesn't use ESM, naming the file as .eslintrc.js is fine. See ESLint's Configuration Files docs for more info.

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 lint build output (make sure it's set to your correct build folder name)
dist

Further Configuration Documentation​

Running ESLint​

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

npx eslint .

That's it - ESLint will lint all TypeScript compatible files within the current folder, and will output the results to your terminal.

You are also recommended to add an npm script in your package.json, so you don't have to repeat the same command every time you run ESLint.

package.json
{
  "scripts": {
    "lint": "eslint ."
  }
}

This way, you can invoke the lint script directly:

npm run lint
note

If you use non-standard file extensions, you will need to explicitly tell ESLint to lint those extensions using the --ext flag

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:

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:

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.