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.

💡

Some problems reported by this rule are manually fixable by editor suggestions.

TypeScript provides several comment directives 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 comment directives supported by TypeScript are:

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

This rule lets you set which comment directives you want to allow in your codebase.

eslint.config.mjs
export default tseslint.config({
  rules: {
    "@typescript-eslint/ban-ts-comment": "error"
  }
});

Try this rule in the playground ↗

Options​

This rule accepts the following options, and has more strict settings in the strict config.

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

type Options = [
  {
    /** Whether allow ts-check directives, and with which restrictions. */
    'ts-check'?: DirectiveConfigSchema;
    /** Whether and when expect-error directives, and with which restrictions. */
    'ts-expect-error'?: DirectiveConfigSchema;
    /** Whether allow ts-ignore directives, and with which restrictions. */
    'ts-ignore'?: DirectiveConfigSchema;
    /** Whether allow ts-nocheck directives, and with which restrictions. */
    'ts-nocheck'?: DirectiveConfigSchema;
    /** A minimum character length for descriptions when `allow-with-description` is enabled. */
    minimumDescriptionLength?: number;
  },
];

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

// These options are merged on top of the recommended defaults
const defaultOptionsStrict: Options = [{ minimumDescriptionLength: 10 }];

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');
}
Open in Playground

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');
}
Open in Playground

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');
Open in Playground

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');
}
Open in Playground

When Not To Use It​

If your project or its dependencies were not architected with strong type safety in mind, it can be difficult to always adhere to proper TypeScript semantics. You might consider using ESLint disable comments for those specific situations instead of completely disabling this rule.

Further Reading​

Resources​