When to Stop and Ship
You'll learn: How to decide when your TypeScript migration is "good enough" to ship, even with remaining .js files.
The Perfectionist's Trap
TypeScript migrations don't need to reach 100% completion before delivering value. The question isn't "when will we finish?" but rather "when have we captured enough safety to ship confidently?"
Think of it like renovating a house while living in it. You don't need to replace every lightbulb before moving back into the renovated kitchen. Some JavaScript files can stay—indefinitely, even.
Acceptable Remaining JavaScript
These files can often stay as .js without risk:
- Build scripts and tooling configuration (webpack.config.js, scripts/)
- One-off migration scripts that run once and are archived
- Test fixtures and mock data where type safety adds no value
- Stable, battle-tested utilities that rarely change and work perfectly
- Third-party code you copied that has no types available
- Prototypes and experimental code not yet in production
These files don't participate in your core application logic. Leaving them in JavaScript doesn't undermine the type safety of your product.
When Full Conversion Is Necessary
Convert everything when:
- Remaining files are in your critical path (core business logic, API routes, database models)
- You're publishing a library where users expect full TypeScript support
- The codebase is small enough that finishing costs less than managing mixed state
- Team policy requires consistency and you have the time to enforce it
- Type errors are leaking from JS files into TS code
If JavaScript files are causing any types to spread through your typed code, they must be converted or stubbed with .d.ts declarations.
The Shipping Decision Framework
Ask yourself:
- Are critical paths typed? (User authentication, payment processing, data validation)
- Can engineers refactor safely? (Do they get errors when breaking changes happen?)
- Is the team productive? (Are type errors helping more than hindering?)
If all three are "yes," you're ready to ship—even at 70% migration.
Key Takeaway: Ship when your critical paths are type-safe and your team is productive, not when every file is converted. Perfection is the enemy of delivering value.