Use "@ts-expect-error" over "@ts-ignore" in TypeScript

TypeScript provides several directive comments which allow you to suppress TypeScript compiler errors. The directive comments supported by TypeScript are:

To ignore errors on specific lines
// @ts-expect-error
// @ts-ignore

To skip checking some files
// @ts-nocheck

To enable errors
// @ts-check

Have you wondered why TypeScript team bothers to provide 2 comments to ignore errors on particular lines?

Let's say we have a function called sum that adds numbers.

function sum(num1: string | number, num2: string) {
   return Number(num1) + Number(num2)
}

sum(1, 2)
// Triggering an error ❌
// Argument of type 'number' is not assignable to parameter of type 'string'.ts(2345)

When you don't have time to fix the error right away because the code is working fine in runtime, you decide to use @ts-ignore to ignore the type error.

function sum(num1: string | number, num2: string) {
   return Number(num1) + Number(num2)
}

// @ts-ignore
sum(1, 2)

The following day, you discover that the type of num2 should be string | number, like num1, rather than just a string.

function sum(num1: string | number, num2: string | number) {
   return Number(num1) + Number(num2)
}

// @ts-ignore
sum(1, 2)

Here's the risky part. When you use @ts-ignore, you're breaking the type safety of the code. Even though your code is working fine, the type checking is ignored.

That's why TypeScript team provides another directive comment to ignore the type error. It's @ts-expect-error.


Now, let's go back to the previous error, when num2 type is only string and we use @ts-expect-error instead of @ts-ignore.

function sum(num1: string | number, num2: string) {
   return Number(num1) + Number(num2)
}

// @ts-expect-error
sum(1, 2)

After num2 type is fixed, it will trigger an error that says Unused '@ts-expect-error' directive.. This means that the type is already correct and there's no need to ignore the type error anymore.

You can remove the @ts-expect-error.

function sum(num1: string | number, num2: string | number) {
   return Number(num1) + Number(num2)
}

// @ts-expect-error
sum(1, 2)
// Triggering an error ❌
// Unused '@ts-expect-error' directive. ts(2578)

Conclusion

Sometimes, developers face situations where they need to complete a task / project quickly, even if it means compromising the quality of the code, like ensuring proper typing in TypeScript. This often leads to developers temporarily ignoring type errors using @ts-ignore with the intention of fixing them later. But, this approach can lead to bigger issues in the future.

This is why TypeScript team provides another directive comment known as @ts-expect-error. Unlike @ts-ignore, it doesn't completely ignore the type error.

Bonus

You can install @typescript-eslint and enable one the rules named prefer-ts-expect-error (https://typescript-eslint.io/rules/prefer-ts-expect-error).

The rule will automatically replace @ts-ignore to @ts-expect-error.

// @ts-ignore ❌
sum(1, 2)

// @ts-expect-error ✅
sum(1, 2)