Understanding TypeScript’s Comments: @ts-ignore, @ts-expect-error, and Friends

When working with TypeScript, you've probably seen some strange-looking comments like // @ts-ignore or // @ts-expect-error. These are TypeScript directives, often called “magic comments” — and they can change how the compiler behaves for specific lines or files.
what exactly is it? what are the difference?

Let's walk through the 4 most important directives you should know.

1. // @ts-expect-error

This directive tells TypeScript:

“I expect the next line to throw a type error. If it doesn't, fail the build.”

// @ts-expect-error
const name: number = "John"

If the error is later fixed (intentionally or by accident), the compiler throws an error:

Unused '@ts-expect-error' directive.

✅ Why it's good:
• Enforces that you're suppressing an error on purpose.
• Helps with testing or gradually migrating code.

🛠 Use when:
• You're writing a test that expects an error.
• You're temporarily keeping known type errors but want safety.

2. // @ts-ignore

This tells TypeScript:

“Ignore all errors on the next line. I know what I'm doing.”

// @ts-ignore
const user: string = 123

Unlike @ts-expect-error, this will never alert you even if the error is gone later. It's silent and dangerous if overused.

⚠️ Why it's risky:
• Suppresses all type checking on that line.
• Can hide bugs and technical debt.

🛠 Use only when:
• There's no other option.
• You're integrating with legacy code, third-party libs, or non-typed APIs.

I would avoid this at all cost.

3. // @ts-check (for .js files)

This enables TypeScript type-checking for plain JavaScript files.

// @ts-check

/**
 * @param {number} x
 * @returns {number}
 */
function square(x) {
  return x * x
}

🔍 Why it's useful:
• Allows you to catch type bugs in JS without migrating to .ts.
• You can annotate with JSDoc for full type checking.

🛠 Use when:
• Gradually migrating a JS codebase to TS.
• You want lightweight type safety in JS.

4. // @ts-nocheck

Disables all TypeScript checking for a file even in .ts or .tsx.

// @ts-nocheck

const user = getUser()
user.doSomethingThatDoesNotExist()

💀 Why it's dangerous:
• Completely disables the TypeScript compiler for that file.
• Silently ignores all type and syntax errors.

🛠 Use only when:
• You're working with untyped legacy code.
• You're debugging or temporarily disabling TS during migration.

---

Overall, my take:
• Prefer @ts-expect-error over @ts-ignore for long-term maintainability.
• Use ESLint rules like @typescript-eslint/ban-ts-comment to restrict or require justification for using these comments.
• In a real project, flag every @ts-ignore for later cleanup.

| Directive          | Scope       | Description                                      | Safe? |
|-------------------|-------------|--------------------------------------------------|--------|
| `@ts-expect-error` | One line    | Expect a type error. Fails if no error.         | ✅     |
| `@ts-ignore`       | One line    | Ignore any TS error on the next line.           | ⚠️     |
| `@ts-check`        | Whole file  | Enable TS checking in JS files.                 | ✅     |
| `@ts-nocheck`      | Whole file  | Disable all TS checking.                        | ❌     |

Use them wisely to reduce friction, not to hide problems.

This article is part of my personal note, as reminder of problems and learnings i encounter on my daily work. I did use AI to help build the article.
If you interested, follow.

Author: @rickvian