A particular project at work started as a rapid MVP. A lot of corners were cut to get it running. At the time, I hadn’t learned TS yet, so I built the codebase in JS. Fast forward a year and the project had reached a level of adoption and complexity where it was time to go back and strengthen the foundation.

One of the biggest decisions we made was moving to TypeScript. Both my coworker and I had minimal experience, so we were learning and migrating at the same time. We’re super happy with the results. Here are the details:

Benefits

• Explicit. Each type acts as documentation, making the code easier to understand. VSCode works so much better with TS. You can hover over things, refactor more easily, and more.
• Catches bugs earlier. TS flags issues at compile time instead of runtime, preventing subtle errors before they happen.
• Encourages cleaner architecture. Types force better organization and design decisions.

Implementation Details

• 382 types
• 28 enums
• 1 interface
• 74 Vue files converted
• 54 JavaScript files converted

Piecemeal Approach

Instead of converting everything at once, we migrated gradually. This allowed us to:

• Learn TypeScript through real use cases.
• Test thoroughly as we went.
• Avoid disrupting ongoing development.

We started with reusable components and utilities, which provided the best coverage investment. For domain-specific components, we worked from the bottom of the component tree upward. We also organized types and utilities by domain, which made dependencies more explicit to other developers.

Update 2025: After a few years using Domain-Based Architecture, I’m not sure it was the best choice for this codebase. I love the explicitness, but it’s hard to teach and requires constant PR vigilance. Next time, I might go with a flatter structure. Domain-based organization is probably best for personal projects or very small teams.

Total conversion time: 5 months, with a 20% capacity allowance in relation to feature work.

• Included learning TypeScript.
• Included learning migration strategies.
• Included learning architecture best practices.
• Done as a secondary priority to product features.

We’re excited to see how this migration impacts our development long-term. The process uncovered a bunch of sneaky bugs we were able to fix. With this project being a key tool for our employer, built for the long haul with lots of new features coming, we’re glad to have laid a solid foundation for a stable and extensible product. ❤️

Update 2025: I’ve fully bought in. I can’t imagine going back to JavaScript. Every time I work with a JS-only codebase or package, I feel naked. Very happy we made the switch.