Skip to content
Tutorials Center
My learning

Topics

TypeScript Reference ยท Modules and Declaration Files

TypeScript @types packages and the types field

Reference for @types packages in TypeScript: how DefinitelyTyped works, how packages ship their own types, and how typeRoots and types control what loads.

When you import a JavaScript package, TypeScript needs type information for it. There are three places it can come from: the package itself, a separate @types/name package, or a declaration you write yourself. The @types scope on npm is where the community project DefinitelyTyped publishes declaration-only packages for libraries that do not ship their own types, for example @types/node or @types/express.

A package that ships its own types points to them from package.json with the types field (or typings), or through exports conditions. Modern libraries are usually written in TypeScript and generate their own declarations, so @types is mostly needed for older or plain-JavaScript packages.

TEXT
npm install express
npm install --save-dev @types/express   # types for a package that ships none

Try it

TypeScript Types for Node come from @types/node

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or readFileSync(0)), it gets the next line from this box.

TypeScript What a missing declaration looks like

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or readFileSync(0)), it gets the next line from this box.

Syntax

JSONC
// package.json of a library
{
  "name": "my-lib",
  "main": "./dist/index.js",
  "types": "./dist/index.d.ts",
  "exports": {
    ".": { "types": "./dist/index.d.ts", "import": "./dist/index.js" }
  }
}

// tsconfig.json of an app
{
  "compilerOptions": {
    "typeRoots": ["./node_modules/@types", "./types"],
    "types": ["node"]
  }
}
Setting Description
types / typings in package.json Path to the entry declaration file of a package.
exports with a types condition The modern form. Put "types" first in each condition object, because conditions are matched in order.
typeRoots Folders whose subfolders are treated as global type packages. Default: every node_modules/@types from the project upward.
types If set, only the listed packages from typeRoots are included as globals. Use "types": [] to include none.

Edge cases: typeRoots and types only control packages included automatically as globals (such as describe from @types/jest). A package you import is always resolved through normal module resolution, whatever these options say.

Usage notes

  • Install types as dev dependencies. @types/* packages are only needed at compile time.
  • Version alignment. Match the major version of @types/x with the library when you can (@types/node@24 for Node 24). Types can lag behind the library.
  • Check before installing. If the package has a types field, an exports.types condition or a .d.ts next to its main file, it already ships types and @types is redundant.
  • Scoped names are mangled: types for @scope/pkg live in @types/scope__pkg.
  • The missing-types errors. TS7016 means a JavaScript package was found but has no types; TS2307 ("Cannot find module ... or its corresponding type declarations") means nothing could be resolved at all. The quick fix for TS7016 is an ambient shorthand module, the proper fix is @types or a real declaration file.
  • Global leakage. All @types/* packages in node_modules load globally by default, which can make test globals appear in application code. Restrict them with types.