When to Graduate to Full TypeScript
You'll learn: How to recognize the moment when @ts-check stops being enough and adopting full TypeScript becomes the smarter investment.
The Limits of @ts-check
You've been using @ts-check and JSDoc to add type safety to your JavaScript files—it's been great for catching bugs and documenting your code without changing your build process. But there comes a point where you'll feel the friction.
@ts-check cannot:
- Define enums (you're stuck with object literals or string unions)
- Use advanced utility types like
Pick,Omit,Record, or conditional types - Import type-only declarations cleanly (everything must be a runtime value or wrapped in JSDoc)
- Express complex generic constraints or mapped types elegantly
- Provide first-class interface definitions that are truly separate from runtime code
The Tipping Point
Think of @ts-check like training wheels: they're fantastic while you learn balance, but eventually they limit how fast you can go. If you find yourself writing increasingly complex JSDoc comments that feel verbose or clunky, or if your team is already comfortable with TypeScript concepts, it's time to consider .ts files.
Common signs you've outgrown @ts-check:
- You're working around the lack of enums with convoluted patterns
- Type definitions are becoming longer than your actual code
- You need sophisticated type transformations or generics
- Your project is growing and you want better refactoring support
- Third-party libraries you use are TypeScript-first
Full TypeScript gives you a proper type system, better tooling, and cleaner syntax—but requires a compilation step.
Key Takeaway: Graduate to full TypeScript when @ts-check's inability to handle enums, advanced types, or type-only imports starts slowing you down more than its simplicity speeds you up.