Installing Type Definitions with @types

Installing Type Definitions with @types — the core idea

The @types scope hosts community declaration packages for JavaScript libraries that do not ship their own TypeScript types. Some libraries already include types, so an additional @types dependency may be unnecessary. Match the declaration version and actual runtime API.

What you’ll learn

Explain installing type definitions with @types with a concrete use case.
Run the example and account for every line of its output.
Recognize the difference between compile-time checking and runtime behavior.

Understand the rules and when to use them

Reading the code: The tiny Callback type illustrates what a third-party declaration provides: the checker knows what arguments a consumer receives and what it must return. The runtime function still comes from the actual package.

Keep the boundary clear: Installing @types/foo is not the same as installing foo. Declarations do not provide executable library code.

See the idea as a flow

Follow the three stages and identify what happens in TypeScript versus JavaScript.

Run the complete TypeScript example

Save the code as installing-type-definitions-attypes.ts. The result below was captured after compiling this exact example with strict TypeScript checking and executing the emitted JavaScript in Node.js.

TypeScript code

type Callback = (code: number) => string;
function useCallback(fn: Callback): string { return fn(200); }
console.log(useCallback(code => `HTTP ${code}`));

Verified output

HTTP 200

Build: npx tsc --strict --target es2022 --module commonjs --lib es2022,dom,esnext.disposable installing-type-definitions-attypes.ts; run: node installing-type-definitions-attypes.js. The exact filename may be changed freely. When a multi-file project exists, prefer its tsconfig.json and build scripts.

Trace the example line by line

The tiny Callback type illustrates what a third-party declaration provides: the checker knows what arguments a consumer receives and what it must return. The runtime function still comes from the actual package.

The output shown above comes from the initialized values in this program. Replacing a type annotation alone does not transform a JavaScript value.

Avoid this common mistake

Installing @types/foo is not the same as installing foo. Declarations do not provide executable library code.

Check both the TypeScript diagnostic and the emitted JavaScript behavior. A program can compile correctly and still need runtime validation or error handling.

Practice independently

Inspect package.json types/typings for a dependency, then check whether an @types package is needed.

Before running your change, write down the type you expect TypeScript to infer and the output you expect JavaScript to print. Then check both predictions.

What to remember

The @types scope hosts community declaration packages for JavaScript libraries that do not ship their own TypeScript types.

Try the practice change and re-run the exact program to test your understanding.

Reaching the recap and completing the quizzes are separate milestones.

Next lesson: Ambient Declarations →