Stop Using .d.ts Files in TypeScript

Matt Pocock on X, is telling everyone to stop using .d.ts files in your TypeScript projects forever. Here is a tweet from his reinforcing his position:

TL;DR: Never use .d.ts files.

Keep in mind, this is Matt Pocock, the TypeScript wizard, so this post should be taken seriously.

However, is he right? Should you open your favorite editor and replace all your .d.ts files with .ts?

Well in this article, we will answer this question by explaining the purpose of .d.ts files, then I will prove to you why Matt is correct, and why you should never write .d.ts code again.

So without further ado... Let's dive right in!

The Purpose of .d.ts Files

Lets start off by clarifying that .d.ts files are not useless.

TL;DR: Their purpose is to hold declarations (not implementations) and public types.

.d.ts files are therefore strict blueprints which represent the types that your source code can use.

I mentioned that .d.ts files can only contain declarations, so lets look at a code example to see the difference between a declaration and implementation for a function that adds two numbers:

As you can see, the add function implementation actually shows the addition being carried out, and the result returned, while the declaration doesn't.

Now how would .d.ts files be used in practice?

Well let's take the example of the add function, and imagine we have two files, add.d.ts and add.js storing the declaration and implementations respectively.

Now lets create a new file index.js which will actually use the add function:

Note that you will have typesafety inside this JS file for this add function because the function is annotated with the type declaration inside add.d.ts.

Why .ts Files Are Better

So we looked at how .d.ts files work, and why they are useful, but why then, is Matt right?

He is right because you can directly create a .ts file with annotated types and implementation inside a single file.

I.e. Having a single add.ts file, containing both the declaration and implementation, is the equivalent of having the add.d.ts and add.js files defined separately.

This means you don't need to worry about organizing declaration files with their respective implemention files, which is great for developer experience.

However, a popular argument for .d.ts being "better" is that you need it for library code distribution.

Using .d.ts files alongside your compiled JavaScript source code is much more efficient that storing a .ts file, because all you really need are the type declarations for users to have typesafety when using your library.

And this is all true, but this argument is moot because you can simply auto-generate .d.ts files from your .ts files, just by changing a few settings in your package.json and tsconfig.json files as follows:

• tsconfig.json: Make sure to add declaration: true in order to support .d.ts file generation.

• package.json: Make sure to set your "types" property to the .d.ts file that is generated next to your compiled source code.

Auto generating your .d.ts files will give you all of the benefits without having to actually write them yourself.

Sticking The Nail in The Coffin

Everything you can do in a .d.ts file you can do inside a .ts file.

This can be achieved using the declare global {} syntax inside a .ts file.

Anything inside the curly braces will be treated as global ambient declarations, and this is essentially how .d.ts files work as a whole.

So the bottom line is, .ts files have the ability to store ambient declarations, which means you can still have globally accessible types without a .d.ts file.

To make matters worse, most projects will use the tsconfig option skipLibCheck to true. This will remove typesafety from not only external .d.ts files, but also your own ones.

This means types defined in a .d.ts file could be wrong and you won’t even be aware of this!

Therefore, .d.ts files are indeed pointless to write, 99% of cases are better suited to the usage of .ts files, for improved developer experience and lower chances of causing type errors for library code.

So my conclusion is, yes, Matt is right, .d.ts files should never be written, only auto-generated.

Also I would love to hear your counter-arguments in the comments section.

Want to ship code like a hacker? Visit Next Inject⚡ today!

If you enjoyed this article, please make sure to Subscribe, Clap, Comment and Connect with me today! 🌐