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 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.
module.exports = {
"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 = [
{
'ts-check'?: DirectiveConfigSchema;
'ts-expect-error'?: DirectiveConfigSchema;
'ts-ignore'?: DirectiveConfigSchema;
'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.
- ❌ Incorrect
- ✅ Correct
if (false) {
// @ts-ignore: Unreachable code error
console.log('hello');
}
if (false) {
/* @ts-ignore: Unreachable code error */
console.log('hello');
}
Open in Playgroundif (false) {
// Compiler warns about unreachable code error
console.log('hello');
}
Open in Playgroundallow-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' }
:
- ❌ Incorrect
- ✅ Correct
if (false) {
// @ts-expect-error
console.log('hello');
}
if (false) {
/* @ts-expect-error */
console.log('hello');
}
Open in Playgroundif (false) {
// @ts-expect-error: Unreachable code error
console.log('hello');
}
if (false) {
/* @ts-expect-error: Unreachable code error */
console.log('hello');
}
Open in PlaygrounddescriptionFormat
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 .+$' } }
:
- ❌ Incorrect
- ✅ Correct
// @ts-expect-error: the library definition is wrong
const a = doSomething('hello');
Open in Playground// @ts-expect-error: TS1234 because the library definition is wrong
const a = doSomething('hello');
Open in PlaygroundminimumDescriptionLength
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:
- ❌ Incorrect
- ✅ Correct
if (false) {
// @ts-expect-error: TODO
console.log('hello');
}
Open in Playgroundif (false) {
// @ts-expect-error The rationale for this override is described in issue #1337 on GitLab
console.log('hello');
}
Open in PlaygroundWhen 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
- TypeScript Type Checking JavaScript Files