DefinitelyTyped: Type Definitions for JavaScript Libraries

WHY IT EXISTS: TypeScript provides safety by knowing the "type" of every variable. But most of the JavaScript ecosystem was written without types. To use these libraries safely, TypeScript needs a description of their APIs, which is what the DefinitelyTyped project provides.

THE MENTAL MODEL: Think of @types packages as a Rosetta Stone for JavaScript libraries. They don't contain any functional code, only "declaration files" (.d.ts) that translate the library's JavaScript functions, objects, and values into a format TypeScript can understand and type-check.

HOW IT WORKS: When you install a library like lodash, the TypeScript compiler looks for its type definitions. If lodash doesn't include them, the compiler checks for a companion package, @types/lodash. If you've installed it, TypeScript uses those files to provide autocompletion and catch errors, like passing a string where a number is expected. This vast collection of type definitions is managed by the community in the DefinitelyTyped GitHub repository.

WHEN TO USE IT: You need an @types package whenever your TypeScript compiler or IDE complains it "Cannot find module ... or its corresponding type declarations" for a JavaScript library you've installed. This is your cue to run npm install --save-dev @types/the-library-name.

WHEN NOT TO USE IT: Avoid installing an @types package for a library that now includes its own types. Many modern libraries are written in TypeScript or bundle their own .d.ts files. Check the library's package.json for a "types" or "typings" field. Installing a redundant @types package can cause type conflicts and build errors.

ONE CANONICAL EXAMPLE: To use the express web server in a TypeScript project, you first run npm install express. Your code import express from 'express'; will cause a TypeScript error. To fix it, you install the type definitions: npm install --save-dev @types/express. Now, TypeScript knows that express() returns an Application object and can provide accurate autocompletion and type checking for methods like app.get(...).