checkJs: Type-Checking JavaScript Without Conversion
What you'll learn: How to enable TypeScript's type-checker on .js files without renaming them to .ts, giving you gradual type safety during migration.
The Problem: JavaScript Files Outside Type-Checking
You've learned that allowJs: true lets TypeScript compile JavaScript files alongside TypeScript. But by default, TypeScript doesn't type-check those .js files—it just passes them through. This means you can have type errors lurking in your JavaScript code that TypeScript silently ignores.
What checkJs Does
The checkJs compiler option tells TypeScript: "Treat JavaScript files as if they were TypeScript files for type-checking purposes, but don't require me to rename them."
{
"compilerOptions": {
"allowJs": true,
"checkJs": true
}
}
With this flag enabled, TypeScript will:
- Infer types from your JavaScript code
- Check for type errors based on inferred types
- Respect JSDoc type annotations if present
- Report type mismatches, null/undefined errors, and other safety issues
All without requiring you to change .js to .ts.
When This Matters
During migration, checkJs is your middle ground:
- Initial assessment: Turn it on to see how many type errors exist in your JavaScript codebase
- Incremental safety: Get type-checking benefits before committing to full TypeScript conversion
- Third-party code: Type-check vendored JavaScript libraries without modifying them
- Testing the waters: Let your team experience TypeScript's safety without file renames
The Trade-Off
TypeScript infers types conservatively in JavaScript. You'll get basic safety, but without explicit type annotations (via JSDoc or conversion to .ts), the checking won't be as precise as pure TypeScript.
Think of checkJs as training wheels: useful for the transition, but you'll eventually want the full TypeScript experience.
Per-File Control
You can also enable checking for individual JavaScript files without a global flag using a comment at the top:
// @ts-check
This is perfect for testing type-checking on one file at a time.
Key Takeaway: checkJs: true enables TypeScript's type-checker on JavaScript files during migration, giving you safety without requiring file conversions—a critical step in gradual adoption.