Finding and Installing @types Packages

Every npm package you install in a JavaScript project becomes a potential type problem in TypeScript. Some packages ship their own type definitions. Some have community-maintained types on DefinitelyTyped. Some have nothing. Knowing where to look, what to install, and what to do when nothing exists saves hours of confusion during migration.

How TypeScript finds types for npm packages

TypeScript looks for type definitions in two places:

1. Inside the package itself. Many modern packages include a types or typings field in their package.json pointing to a bundled .d.ts file. If this exists, installing the package is enough — no separate install needed.

2. In the @types scope on npm. The DefinitelyTyped project maintains community type definitions for packages that don't bundle their own. You install these separately: npm install --save-dev @types/package-name.

You can tell which situation applies by running npm info <package> types typings after installing the package. If it returns a path like dist/index.d.ts, the types are bundled. If it returns nothing, you need @types.

Packages that bundle their own types

These packages need no additional installation — their types are included:

Common @types packages for QA projects

These packages require a separate @types install:

# Always install for Node.js projects
npm install --save-dev @types/node
 
# Test frameworks
npm install --save-dev @types/jest        # if using Jest without ts-jest
npm install --save-dev @types/mocha       # Mocha
npm install --save-dev @types/chai        # Chai assertions
 
# Utilities
npm install --save-dev @types/lodash
npm install --save-dev @types/uuid
npm install --save-dev @types/jsonwebtoken
npm install --save-dev @types/cookie
npm install --save-dev @types/supertest   # API testing with supertest

How to check if @types exists

Three ways, fastest first:

Option 1 — try installing it:

npm install --save-dev @types/package-name
# If the package doesn't exist, npm prints a 404 error

Option 2 — search on npm:

npm search @types/package-name

Option 3 — the TypeScript type search tool. The TypeScript website hosts a search at typescriptlang.org/dt/search that queries the entire DefinitelyTyped repository.

Version matching

@types packages follow the major version of the package they describe. If you install lodash@4.17.21, you want @types/lodash@4.x.x — not @types/lodash@5.x.x.

# Check your lodash version
npm list lodash
# lodash@4.17.21
 
# Install matching @types
npm install --save-dev @types/lodash@^4

A major version mismatch produces errors like Property X does not exist on type Y where the method exists in the library but the type definition predates or postdates its addition.

Reading type definitions

Once types are installed, VS Code lets you inspect them directly. Cmd+Click (Mac) or Ctrl+Click (Windows) on any function name from an installed package opens the .d.ts file. This is useful when:

• The autocomplete shows a function but you're not sure of its full signature
• A type error says "Expected X" and you want to see what X actually is
• You need to extend an existing type and want to see its current shape

For example, clicking into @types/jest shows the full signature for expect, describe, beforeEach, and every matcher — saving you from reading the Jest docs when you're unsure of a method's type.

The "types" field in tsconfig

By default, TypeScript auto-includes every @types package installed in node_modules/@types. If your tsconfig.json has an explicit "types" array, only the listed packages are included:

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

This is intentional in Cypress projects — it prevents browser DOM types from conflicting with Cypress's DOM definitions. But it also means @types/lodash, @types/chai, or any other installed package won't be auto-included. Add them to the array if you use them in that tsconfig's scope.

Handling a package with outdated @types

Sometimes @types/package-name is far behind the package's current version — missing methods, wrong signatures. You'll see errors like:

Property 'newMethod' does not exist on type 'SomeClass'

Even though newMethod was added in version 3.1 and you're running 3.2. Options:

1. Pin the package to the last version the @types covers — npm install package-name@<last-covered-version>.
2. Augment the missing types yourself — add the missing method to the library's interface via module augmentation (covered in Lesson 3 of this chapter).
3. Open a pull request to DefinitelyTyped — if you have time and the package is widely used, the community benefits from the fix.

For a migration, option 2 is usually the fastest unblock.

⚠️ Common mistakes

• Installing @types as a regular dependency instead of --save-dev. Type definitions are a development tool. They don't need to be in your production bundle. Always npm install --save-dev @types/....
• Installing both bundled types and a @types package. For packages that ship their own types (Playwright, Axios), installing @types/playwright or @types/axios introduces a second set of type definitions that can conflict. Check whether the package bundles types before reaching for @types.
• Assuming @types packages are always correct. DefinitelyTyped is community-maintained and sometimes lags behind or contains errors. If you get a type error that seems wrong — the method clearly exists and works — read the .d.ts source to verify.

🎯 Practice task

Audit your project's npm dependencies for type coverage.

1. Open package.json and list all dependencies in dependencies and devDependencies.
2. For each package, check whether it bundles types: npm info <package> types typings. Note the result.
3. For packages without bundled types, check if @types/<package> exists on npm.
4. Install any missing @types packages you find.
5. Run npm run type-check. Did any new type errors appear now that TypeScript knows the correct signatures? Fix them.
6. Stretch: pick one installed @types package. Open the .d.ts file (Cmd+Click on any function from that package in VS Code). Find the interface or type that describes the main export. Read its full shape. This is a skill you'll use repeatedly during migration — understanding the type you're working with, not just the error message.