The @ts-nocheck Directive for File-Level Opt-Out
What you'll learn: How to completely disable TypeScript's type-checking for specific JavaScript files when you've enabled checkJs project-wide.
The Opposite of @ts-check
You've just learned about @ts-check, which opts individual JavaScript files into type-checking. The @ts-nocheck directive does the exact opposite—it opts files out of type-checking when you've enabled checkJs: true in your tsconfig.json.
Think of it like this: checkJs turns on type-checking for all JavaScript files in your project. But sometimes you have that one messy legacy file that would produce hundreds of errors. Rather than fix them all immediately, @ts-nocheck lets you say "skip this file for now."
Basic Syntax
Place the directive at the very top of your JavaScript file as a special comment:
// @ts-nocheck
// Everything below this line is completely ignored by TypeScript
function messyLegacyCode(data) {
return data.property.that.might.not.exist;
}
let implicitAny = getSomething(); // No error even with noImplicitAny
The @ts-nocheck comment must appear before any code or other comments to take effect.
When This Matters
This directive becomes valuable during gradual migration when:
- You've set
checkJs: trueto get type-checking benefits across your JavaScript codebase - Most files benefit from this checking
- But a few files are extremely problematic and not worth fixing immediately
- You want to migrate incrementally without blocking progress
It's essentially a surgical escape hatch that says "I know this file has type issues, but I'm acknowledging that and choosing to deal with it later."
The Migration Pattern
@ts-nocheck helps you create a migration priority queue. Mark your worst files with it, fix cleaner files first, then gradually remove the directives as you clean up the legacy code.
Key Takeaway: Use @ts-nocheck to disable type-checking for specific JavaScript files when using checkJs project-wide, allowing incremental migration without getting blocked by legacy code that would otherwise produce overwhelming errors.