TypeScript Migration Overview

[00:00:00]
>> The next topic we're gonna dig into, and it's gonna be over several chapters because this is a really important thing to know how to do when managing a large TypeScript project at scale, like how do you convert a project to TypeScript? And for those of you that already have a TypeScript project, too, we're really talking about how do you continue to evolve a project to stronger, stricter typing, and stricter linting.

[00:00:28]
Everyone is probably in a position where, unless you started out with every single thing in TypeScript, with all your lint rules cranked up to maximum strictness. Lots of cases, you're sort of in some middle state where you wish you could tune things up a little bit more and always trying to do it.

[00:00:48]
But we're just gonna start that whole story of incremental stronger typing from the very beginning where we have duck typing with JavaScript. So, the key thing here is do it in small passes. Don't try to do it all at once and here are my three big tips. So first, stay focused on specific tasks.

[00:01:18]
Particularly if you really like types, It's so tempting to try to look at a file and make it a strongly typed as you possibly could, and then move on to the next file. The danger here is that you can end up changing the behavior of code through improving the types.

[00:01:35]
It's really easy for bugs to sneak in. So especially at the very beginning of this journey, like where we're typing things as any, sometimes we know that I should probably create an interface for this thing and just having the restraint to make incremental passes. So, it's almost like you're doing small layers of improvement.

[00:01:55]
Even though you know you wanna go to a great place, just stay disciplined about completing tasks and get there slow and steady. Make sure you have a solid test suite, right? We talked about how sometimes there's the possibility of values being null, and your JavaScript code might not handle that properly.

[00:02:13]
But sometimes fixing that problem like it'll change your runtime behavior. And if you have no test coverage, It's really hard to catch things like that. The way you achieve stronger typing, it's not very often the case that you can avoid perturbing the way the code behaves at all.

[00:02:34]
You got to make some changes, right? Like introducing a type guard, for example, that's like a new function that ends up being invoked, and it exists at runtime. And then, finally, don't let the perfect be the enemy of the good. Take advantage of the whole one of the big benefits of TypeScript, it's not supposed to feel like a rewrite.

[00:02:52]
It's not like you have a big Ruby code base, and you're trying to rewrite it in Java or something like that. There's been a lot of hard work that has gone into making TypeScript something that you can sort of digest in small bites. Don't forget that, and don't forget to benefit from that, it's a good thing.

[00:03:14]
All right, I [LAUGH] used to have what I called a three-step approach, and it's not really three steps. Step one and two are nice and approachable, and step three was like and then do the rest, do all the other things. So, I have gotten a lot more detailed here.

[00:03:30]
We're gonna talk about this, and together, we're not gonna do every single one of these things. But I made these 11 steps now. I made this mostly so that you can take it home you can study it if you're trying to figure out where you are on this roadmap of getting to stronger and stronger types.

[00:03:49]
It's something that you could sort of look at with some suggestions for orders of doing things, turning on certain linting rules one at a time, and fixing all those things bit. So we're gonna get through step 5 for sure, yes. And then the reason I stopped there is cuz it's a lot of the same, where you add a new linting rule or fix a compiler, turn on a compiler setting, and then things will light up and we'll go and address those, but you're in that cycle.

[00:04:24]
At that point, and it's just sort of like methodical work to get there, like, I don't have any special tips that I haven't written down in this list for that piece. So, step one this is like a small step as I can make it. You wanna get TypeScript into your build toolchain, and we're gonna do that without even renaming our files to ts files.

[00:04:46]
We have some good js dot comments that have type information in them. TypeScript will use that where it can, and this is sort of the maximally relaxed mode we can operate in. Then we're gonna rename all of our files from js to ts. Don't worry. I've written a script for you that will do this.

[00:05:08]
You're not gonna be going to 50 files and changing their extensions. But just the idea that something becomes a type script file that will require us to fix some more things because not everything can be type-checked. In the typescript way, purely using JsDoc types. So we'll fix a couple of things there, so don't forget to read this.

[00:05:33]
Start with TypeScript in the most permissive possible mode. We will allow implicit endings. Step 3 is getting rid of implicit endings, and this, I think, is one of the most important things to enable early because it's part of observability, right? Meaning handling errors properly so you don't get square bracket object, object serialized into Splunk, or whatever you're using to track User errors.

[00:06:02]
Having that early in the process gives you more safety for the rest of the process. And this is where I recommend bringing in definitely typed packages. Although we may bring in earlier, these are missing types for JavaScript libraries that are already in our project. We'll talk a little more about definitely typed, but for now, I'll just say they're community author types that are meant to sort of match a JS library.

[00:06:28]
Very much the same thing as in our little library here. They're just this declaration file handwritten to match this, which would be like, Lodash would publish this or something like that or React. Step four is where we're gonna start doing some domain modeling. We're gonna model re-create interfaces for channel and message and team and user and start threading those through some React components and things like that.

[00:06:57]
And then finally, we're working on Boolean expressions like Boolean logic. Text to see whether something's defined or undefined and how Nullish values are treated, and then we'll move on cuz everything else here is just sort of enable a compiler setting or a lint rule. And we keep going and going and going, but you get to a really strict place by the end of this.

[00:07:19]
So I would still I feel like even beyond step 5, this is a pretty good roadmap. And I looked at the way, like some of the Git history for large TypeScript projects I've contributed to, and this is like roughly. This isn't the way I had done it in the past, but it's the way I wish I had done it, cuz I can see a lot of scrambling in places where I switch the order around here.