Acceptable Use Cases for Suppressions
What you'll learn: When suppression comments like @ts-ignore or @ts-expect-error are legitimate tools rather than code smells.
The Principle: Suppressions Are Last Resorts, Not First Choices
While type suppression comments disable TypeScript's safety checks and should generally be avoided, there are legitimate scenarios where they're the pragmatic choice. These situations typically involve external factors beyond your control: broken third-party libraries, mid-migration states, or tooling limitations.
Three Acceptable Use Cases
1. Working Around Library Bugs
Sometimes a library's type definitions are incorrect or outdated. You know the runtime behavior works, but TypeScript complains due to faulty types. Rather than waiting months for a fix, a suppression with a clear comment is acceptable:
The key here is temporary: you're acknowledging the library's types are wrong, not your code. Link to the GitHub issue tracking the fix.
2. Temporary Migration States
When gradually migrating a large codebase from JavaScript to TypeScript, or upgrading a library with breaking type changes, you might have intermediate states where partial typing creates false errors. Suppressions can unblock migration progress:
The suppression buys time to complete the migration systematically rather than blocking all progress.
3. Tooling Limitations
Occasionally, TypeScript's type system cannot express something that's provably safe at runtime, or build tools interact poorly with specific type patterns. Examples include complex metaprogramming or bundler-specific behaviors:
These are rare, but when the type system hits its limits, a documented suppression is honest.
The Documentation Requirement
All acceptable suppressions must include:
- Why the suppression is needed
- What the expected future resolution is
- Links to issues or documentation
Without context, future maintainers (including yourself) won't know if the suppression is still necessary.
Key Takeaway: Suppression comments are acceptable when addressing library bugs, temporary migration states, or genuine tooling limitations—but only with clear documentation explaining why the suppression exists and when it can be removed.