What is the use-case of enabling declaration and declarationMap in tsconfig.json?

Question

If we enable sourcemap which allows us to debug on the browser. Likewise looking for the use case of declaration and declarationMap.

I have searched over the internet, but my bad could not found the actual use case except generating .d.ts file.

Answer 1

Generating .d.ts files is exactly the use case for declaration compiler option, so the build output is .js, while all type definitions can be still preserved for other TS projects consuming your project.

The IDE can make use of declarationMap option to provide better developer experience: It enables you to quickly navigate to the original sources, when you currently have a corresponding .d.ts file open and want to see its implementation (see also this answer).

Enabling --declarationMap alongside --declaration causes the compiler to emit .d.ts.map files alongside the output .d.ts files. Language Services can also now understand these map files, and uses them to map declaration-file based definition locations to their original source, when available.

In other words, hitting go-to-definition on a declaration from a .d.ts file generated with --declarationMap will take you to the source file (.ts) location where that declaration was defined, and not to the .d.ts.

Answer 2

As your application grows, it will take longer and longer for the Typescript to typecheck and compile your code. With a large codebase, slow compile times can seriously slow down your development. To overcome this, Typescript 3.0 onward, you can split your big project into smaller sub-projects using Project References. declaration and declarationMap options play a big role here.

---

declaration option

Enabling the declaration option will result in Typescript compiler creating the declaration files (.d.ts). The .d.ts files contain the declarations of the types used in your corresponding .ts files. They don't contain the implementations of the types, they just contain the publicly accessible type declarations.

So, anyone can use the types from your Typescript project in some other Typescript project. The compiler can typecheck the code in that other project with the help of your .d.ts files even though they don't have the access to your project.

This is the thing that helps when you split a big project into smaller multiple sub-projects. Sub-projects have access to each other's declaration files. When one of your sub-project (say B) depends on the types declared in the other sub-project (say A), the compiler uses the .d.ts files from the sub-project A to typecheck and compile the sub-project B without the need for compiling the sub-project A again. This results in faster compile times in large projects.

---

declarationMap option

When you enable the declarationMap option, the Typescript compiler creates the declaration source map (.d.ts.map) files. The declaration source map files contain mapping definitions that link each type declaration generated in .d.ts files back to your original source file (.ts). The mapping definitions in these files are in JSON format.

These are used by your editor/IDE. You’ll be able to use editor features like “Go to Definition” and Rename to navigate and edit the code across sub-projects. That means, for example, if you rename a type in one sub-project, the change will be propagated to the other sub-projects too.

---

Note that you can use these options even if you don't split your project. This is useful if you want to have the editor feature “Go to Definition” for .d.ts files. If you hit “Go to Definition” on a declaration from a .d.ts file, you will be taken to the source file (.ts) location instead of location of .d.ts. But these options really shine in split projects.

That's it! Hope that helps.

If you have a project with more than 150 files or so, it's recommended to split it into smaller sub-projects using Project References.