When working in a large team (and I would argue even alone: anyone been wondering what is that code they wrote 6 months ago?), documentation is important. I have been using JSdoc in the past, writing comments on top of functions, most of the times to explain what are the parameters passed, what the function returns, and maybe a description of the function.
Comments are hard to maintain and will become a pain really quickly. They are rarely updated and can cause more confusion than anything else when you have to wonder if they are still relevant. I saw comments in PRs about updating comments, and really, nobody wants to spend time writing this in reviews.
Any code should be self-documented, and TypeScript can help with self-documenting your code as it will allow to describe your parameters type and return type as part of the code, instead of having to write comments above it.
Ever wrote some code to discover you made a typo when calling the function or tried to access a property on a null or undefined object and realised it when it happened in production to your user?
Well, with TypeScript, you will catch major errors quickly on compile time rather than runtime. You will see much less of Uncaught TypeError: Cannot read property “foo” of undefined.
Even better, if you’re using an IDE that allows it, auto-completion works well with TypeScript and it will show you available properties or function as you write code. So typos will be a thing of the past.
When refactoring, I really saw the power of TypeScript. No one’s code is perfect the first time they write it, and it’s ok. If I rename a function or a variable that is used in multiple files and forget a few places (because I’m only human), TypeScript will let me know on compile-time straight away. Now you can refactor code while being confident it will not break your application (no more deploying and closing your eyes).
Navigating ever growing codebase are time-consuming and figuring out what functions are available to you and where is hard. Defined types on your functions make it easier for your teammates and newcomers to use your API and call your function with the right semantic, preventing bugs while coding rather than in QA phase. This will increase your development process and allow you to ship features and bug fixes faster.
The same way writing tests allows you to think better about your code and write it in a better way (we all write test, right?), TypeScript will have you think about your code deeper, especially if you set it to avoid implicit any.
To describe your object, you’ll have to write interfaces to tell TypeScript about their structure, type and what it should expect. That will make you think about your structure more and also improve readability for future you or teammates.
Interfaces are also a great tool to use during spikes and help to get ahead of coding while you’re figuring out the needs and structure.
6 years ago, I made the switch from pure CSS to Sass, and never looked back. All teams I have been in were using Sass as well, and it made us really productive. I use Sass as a default in my project.
My relationship to TypeScript is similar. I use it by default on all projects I started recently for all the reasons above. For those thinking it’s over-engineering for a small project, I would argue all small projects become big at some point. I also never worked on a project I didn’t have to maintain or implement feedback after it was developed and TypeScript helps me do it quicker and safer. I completely trust it to help me catch small mistakes, which can have a big impact.
I do really love TypeScript and I find it really easy to use. You don’t have to go full TypeScript on your project and start using classes if you don’t currently. I have used TypeScript on some Vue projects without using classes, and it works fine, I still get the benefits above.
Point is, do what works for you, one step at a time, and use it for reasons that work for your team, and not because it’s trendy.
I hope this helps you make a decision if you should give TypeScript a go, and I strongly encourage you to play with it.