Skip to main content

ban-ts-comment

Disallow @ts-<directive> comments or require descriptions after directives.

✅

Extending "plugin:@typescript-eslint/recommended" in an ESLint configuration enables this rule.

TypeScript provides several directive comments that can be used to alter how it processes files. Using these to suppress TypeScript compiler errors reduces the effectiveness of TypeScript overall. Instead, it's generally better to correct the types of code, to make directives unnecessary.

The directive comments supported by TypeScript are:

// @ts-expect-error
// @ts-ignore
// @ts-nocheck
// @ts-check

This rule lets you set which directive comments you want to allow in your codebase.

.eslintrc.cjs
module.exports = {
  "rules": {
    "@typescript-eslint/ban-ts-comment": "error"
  }
};
Try this rule in the playground ↗

This rule accepts an options object with the following properties:

type DirectiveConfigSchema =
  | boolean
  | "allow-with-description"
  | {
      descriptionFormat?: string;
    };

interface Options {
  "ts-expect-error"?: DirectiveConfigSchema;
  "ts-ignore"?: DirectiveConfigSchema;
  "ts-nocheck"?: DirectiveConfigSchema;
  "ts-check"?: DirectiveConfigSchema;
  minimumDescriptionLength?: number;
}

const defaultOptions: Options = [
  {
    "ts-expect-error": "allow-with-description",
    "ts-ignore": true,
    "ts-nocheck": true,
    "ts-check": false,
    minimumDescriptionLength: 3,
  },
];

Options​

By default, only @ts-check is allowed, as it enables rather than suppresses errors.

ts-expect-error, ts-ignore, ts-nocheck, ts-check directives​

A value of true for a particular directive means that this rule will report if it finds any usage of said directive.

if (false) {
  // @ts-ignore: Unreachable code error
  console.log('hello');
}
if (false) {
  /*
  @ts-ignore: Unreachable code error
  */
  console.log('hello');
}

allow-with-description​

A value of 'allow-with-description' for a particular directive means that this rule will report if it finds a directive that does not have a description following the directive (on the same line).

For example, with { 'ts-expect-error': 'allow-with-description' }:

if (false) {
  // @ts-expect-error
  console.log('hello');
}
if (false) {
  /* @ts-expect-error */
  console.log('hello');
}

descriptionFormat​

For each directive type, you can specify a custom format in the form of a regular expression. Only description that matches the pattern will be allowed.

For example, with { 'ts-expect-error': { descriptionFormat: '^: TS\\d+ because .+$' } }:

// @ts-expect-error: the library definition is wrong
const a = doSomething('hello');

minimumDescriptionLength​

Use minimumDescriptionLength to set a minimum length for descriptions when using the allow-with-description option for a directive.

For example, with { 'ts-expect-error': 'allow-with-description', minimumDescriptionLength: 10 } the following pattern is:

if (false) {
  // @ts-expect-error: TODO
  console.log('hello');
}

When Not To Use It​

If you want to use all of the TypeScript directives.

Further Reading​

Resources​