TypeScript

Typescript is a programming language that extends JavaScript, primarily by adding static type checking.

Key benefits

Type safety with static code analysis for early error detection

Improved developer experience with code completion and documented arguments by default

Enhanced maintainability and scalability allowing faster development and large refactorings

Support for gradual adoption

As your project grows, so do your dependencies, and changing a single line can affect the behaviour of many other files. For example, changing the property of a UI component can break views that use it, and TypeScript’s static type checking will alert you to all the places that need to be updated.

What is static type checking and why does it matter?

Static type checking is a process that provides guarantees about how your code will run. This task is usually performed by your IDE, so you get a very short feedback loop.

It helps prevent common issues such as passing incorrect argument types, accessing properties that may not exist, or invalid parameters for API calls.

Overall the biggest benefit TypeScript will give you is that it will help developers feel more confident in the code they write and save time in validating manually that they have not accidentally broken parts of the project.

Recipies

Adding TypeScript to your project

Install TypeScript as a dev dependency:

pnpm install --save-dev typescript

Generate a default configuration file:

pnpm exec tsc --init

The generated tsconfig.json will probably need some adjustments and it can be overwhelming at first. Fortunately Microsoft maintains great recommendations for TSConfig bases to get you started with for a variety of environments and frameworks. Here you can find the full TSConfig reference.

Total Typescript (Matt Pocock)‘s TSConfig Cheat Sheet is also a great article that demystifies tsconfig.json configuration.

Migrating a JavaScript project to TypeScript

It’s always easier to start a TypeScript project from scratch and immediately reap all its benefits. Yet you might face the situation where you need to migrate an existing JavaScript project to TypeScript in order to get the benefits highlighted above, especially if you often encounter bugs that could have been prevented with a strongly typed system.

Large project (100+ files or 10.000+ lines)

You will want to process gradually with a migration focusing on active code: all new and changed code should be 100% compliant with your TypeScript configuration. At the beginning, anything you’re not touching does not need to be updated.

1. Communicate the game plan to your team
2. Create a strict TypeScript configuration following your project needs
3. Rename all the JavaScript files you want to migrate to TypeScript to .ts
4. Make sure you are able to transpile your TypeScript files through your bundler or an extra build step.
5. Take some item to prepare good types for your core business logi, utils and API contracts that you can later use throughout your project and if possible automatically generate types from your API definition, using for example OpenAPI TypeScript
6. Make it a rule that all new changed code needs to be 100% TypeScript compliant
7. Enforce this rule through your CI setup (if you are using Github Actions, I recommend reviewdog) 8 Use any and ts-expect-error when there’s a type error that’s too deep in a tree to justify the cost of fixing it at the moment
8. Collect and document occurences in your codebase of common TypeScript errors and how to solve them to serve as reference documentation
9. Track your progress and celebrate wins
10. At a later stage of the migration, update the rule for 6-7 to enforce that every time a file is changed, the entirely file should be 100% TypeScript compliant
11. Finalize the migration with a focused push for example using the strategy in the Small project tab

Small project

1. Communicate the game plan to your team
2. Setup a small taskforce with dedicated time which will lead the migration of the entire codebase on a seperate branch
3. On this branch, make sure you are able to transpile your TypeScript files through your bundler or an extra build step.
4. Rebase with your default branch frequently
5. Take some item to prepare good types for your core business logi, utils and API contracts that you can later use throughout your project and if possible automatically generate types from your API definition, using for example OpenAPI TypeScript
6. Migrate your codebase progressively starting with code with less dependencies (leaves in your project dependency tree)
7. Merge the migration branch and perform manual QA

In both cases, having good integration and automated end to end tests, at least on your critical workflows will help prevent downtimes and regressions.