In the vast ecosystem of JavaScript libraries and modules, not all of them are written in TypeScript. Yet, as a TypeScript developer, you still want to enjoy the benefits of type safety and autocompletion when using these libraries. TypeScript declaration files allow us to integrate with these libraries.
By including declaration files in your project, you can use JavaScript libraries with the confidence that you’re maintaining the type integrity and developer experience TypeScript promises. Whether you fetch them from the DefinitelyTyped repository or craft your own, declaration files are indispensable tools in the TypeScript developer’s toolkit.
.d.ts files
A TypeScript declaration file, typically ending with a .d.ts extension, serves a dual purpose.
For libraries written in TypeScript, they often include their own declaration files, ensuring users can seamlessly integrate the library and its types into their projects. Importantly, these files contain only type signatures and descriptions, not the actual implementation, detailing the library’s API for TypeScript awareness.
For libraries not originally written in TypeScript, a declaration file acts as a bridge, providing type definitions that allow TypeScript developers to use the library with type safety.
Libraries with built-in TypeScript declarations
npm and Yarn can include bundled TypeScript declarations (“npm displays packages with bundled TypeScript declarations”), however keep in mind that this will not always be the case.
Usually a well-maintained library will come with its own TypeScript declarations.
You can tell if a library includes its own TypeScript declarations if there is a TypeScript icon on the npm website.
We can see that for the styled-components library there is built-in TypeScript declarations:
Definitely Typed
Definitely Typed, https://github.com/DefinitelyTyped/DefinitelyTyped, is a repo which contains declarations for other projects. It is the go-to solution to find types for a library that doesn’t have built-in TypeScript declarations. This library uses the @types namespace and you might have already seen this in TypeScript projects.
It is important to note that the types added to Definitely Typed are not necessarily maintained by the authors of the library and could possibly be maintained by the community. This means there is the potential that the types are not completely synced up.
If a project is popular and is missing it’s typing, a pull-request can be created with the Definitely Typed repository where, if accepted, it would then be available for other developers to use.
Checking if a repo has types from Definitely Typed
In the images below we have a look at Lodash where you will see that there is a DT badge next to the Lodash name. This means that the library has Definitely Typed types and you can add them to your project.
Above: DT badge on the npm website.
Adding types from Definitely Typed
It’s a straightforward process to add types from Definitely Typed.
Firstly, confirm that the library you want to add has the DT badge on the npm or yarn website. If it does, click the DT icon which will take you to the library’s types in the Definitely Typed/@types repo.
On this page you will find the exact @types/library-name library you need to install, where /library-name is the name of the library you wish to install. You can now install the library shown on this page.
For example, for lodash you would use the following:
npm install --save @types/lodash