Declaration files and DefinitelyTyped

Intermediate · 5 min

What .d.ts files are, where a package's types come from, how @types packages are found through types and typeRoots, and what skipLibCheck skips.

Before thisModules and type-only importsModule resolution

WittCode · 5 min

Declaration files and DefinitelyTyped

The player loads from youtube-nocookie.com when you press play. Nothing reaches YouTube before that.

Taught by WittCodeReport a problem with this video
Not started
Set this lesson's status

What you'll learn

  • A `.d.ts` file holds only types: signatures and shapes with no implementations. It describes JavaScript that exists somewhere else, so the checker can type-check code that uses it.
  • A package's types come from one of two places: the package itself, pointed to by `types` in its `package.json` or a `types` condition in `exports`, or a separate `@types/<name>` package published from the DefinitelyTyped repository.
  • When you import a package, the compiler checks for bundled types first and then looks in `node_modules/@types`. Global types that nothing imports, like Node's `process`, are only loaded if listed in `types`.
  • Since TypeScript 6.0, `types` defaults to an empty list, so projects add entries such as `"types": ["node"]`. `typeRoots` changes which folders are searched for those packages.
  • `skipLibCheck` stops the compiler checking the contents of every `.d.ts` file, your own included. It saves time and avoids errors in dependencies you can't fix, at the cost of hiding mistakes in declaration files.

Most of npm is JavaScript

The compiler can only check a call if it knows the types on both sides. For your own .ts files that’s easy. But most packages on npm ship JavaScript, and a .js file says nothing about what its functions accept or return. Import one with no type information and you get:

error TS7016: Could not find a declaration file for module 'slugify-lite'.
'.../node_modules/slugify-lite/index.js' implicitly has an 'any' type.

The compiler can’t read types out of the JavaScript, and it won’t guess. It needs a separate description of the package’s shape. That description is a declaration file.

What a .d.ts file is

A .d.ts file contains only type information: function signatures, interfaces, the types of exported values. It has no function bodies and emits no JavaScript. Think of it as the datasheet for a chip. It lists every pin and what it expects, so you can design a board around the part without the chip’s internal circuitry in front of you.

// index.d.ts
export interface SlugifyOptions {
  separator?: string;
  lower?: boolean;
}

export declare function slugify(input: string, options?: SlugifyOptions): string;
export declare const version: string;

declare means “this exists at runtime, trust me, here is its type”. The compiler can’t verify that promise. If the declaration says slugify returns a string and the JavaScript returns null, nothing catches it. Declaration files are only as accurate as whoever wrote them.

You already use dozens of these. The lib option from tsconfig explained works by loading files such as lib.es2022.d.ts and lib.dom.d.ts that describe built-in JavaScript and browser APIs.

Where a package’s types come from

Bundled types. Packages written in TypeScript, like zod, compile their own .d.ts files and publish them alongside the JavaScript. Their package.json points to them, either with a top-level "types" field or a "types" condition inside exports, as shown in module resolution. You install the package and the types come with it.

DefinitelyTyped. For packages written in plain JavaScript, the community maintains declarations in one large GitHub repository, DefinitelyTyped. Each one is published to npm under the @types scope:

npm install express
npm install --save-dev @types/express

@types packages are versioned to follow the library’s major and minor version, so @types/express@5.0.x describes express@5.0. Scoped packages get a double underscore: types for @babel/core live in @types/babel__core. The editor will often suggest the right npm install when it shows TS7016.

How the compiler finds them

There are two separate paths, and mixing them up causes most confusion.

Imports. When you write import express from "express", module resolution looks for the package’s own types first. If it finds none, it looks in node_modules/@types/express. Nothing else needs configuring.

Globals. Some type packages declare globals that nothing imports: process and Buffer from @types/node, or test functions like describe from @types/jest. @types/node also declares Node’s built-in modules, such as node:fs, from inside itself rather than as separate packages. None of this loads unless the package is listed in the types option:

{
  "compilerOptions": {
    "types": ["node"]
  }
}

Since TypeScript 6.0, types defaults to [], so a project relying on Node globals has to say so. Before 6.0, every package in node_modules/@types was loaded automatically, and older guides assume that. "types": ["*"] restores the old behavior. typeRoots changes which folders those names are looked up in. It defaults to node_modules/@types, and you’ll rarely need to change it.

skipLibCheck

Every .d.ts file loaded into your program gets type-checked, and a large project can load thousands of them from dependencies. Some contain errors you can’t fix, or two packages declare the same global in conflicting ways. skipLibCheck: true skips checking the contents of all declaration files. Your code is still checked against them.

Most projects turn it on, and the tsconfig lesson recommends it. The catch is that it skips every .d.ts file, including ones you write. That’s a good reason to keep application types in ordinary .ts files and use .d.ts only for describing JavaScript.

What the video covers

WittCode’s video is under five minutes and very concrete. It explains what a .d.ts file is, writes a small custom one, then installs @types/express and opens node_modules/@types to show where those declarations live. It doesn’t cover types, typeRoots, or skipLibCheck, and it was made before TypeScript 6.0 changed the types default, so those parts come from the sections above. Matt Pocock’s video in the links expands on the skipLibCheck warning. Writing declarations for an untyped package and extending existing ones is the next lesson, writing declaration files and module augmentation.

Check yourself

  1. 01You import an untyped JavaScript package and get `TS7016: Could not find a declaration file for module`. What are your options, in order of preference?

    First check whether an `@types` package exists for it and install that as a dev dependency. If not, write your own declaration for the module in a `.d.ts` file. As a last resort, a one-line `declare module "name";` makes everything from it `any`, which silences the error without giving you any checking.

  2. 02Why doesn't `zod` need an `@types/zod` package while `express` needs `@types/express`?

    Zod is written in TypeScript and publishes its own `.d.ts` files, pointed to from its `package.json`. Express is written in JavaScript and doesn't ship types, so the community maintains them separately on DefinitelyTyped, published to npm under the `@types` scope.

  3. 03You've installed `express`, `@types/express`, and `@types/node`. `import express from "express"` is typed correctly, but `process.env` gives `Cannot find name 'process'`. What is going on?

    The `express` import finds `@types/express` through module resolution, which needs no configuration. `process` is a global that nothing imports, so `@types/node` only loads if `node` is in the `types` list, which is empty by default since TypeScript 6.0. Adding `"types": ["node"]` fixes it.

  4. 04Why might turning on `skipLibCheck` hide a real bug in your own project?

    It skips checking every `.d.ts` file, not just those in `node_modules`. If you put your application's types in a `.d.ts` file, mistakes in it are no longer reported, which is one reason to keep app types in ordinary `.ts` files.

Go deeper

Notes

Private to you

Esc
↑↓ navigate↵ open? shortcuts

Keyboard shortcuts

Press Esc to close

Anywhere

⌘K
Search and commands
/
Search
?
This sheet
Esc
Close

Reading a lesson

J
Next lesson
K
Previous lesson
B
Bookmark