Chapter 8.4☕ 15 min read

Third-party Types (@types/...)

Bridging the gap between JavaScript and TypeScript

01The Embassy Translator

Most of the JavaScript ecosystem was built WITHOUT TypeScript. When you npm install a library like Express, Lodash, or React, it's JavaScript — no types! TypeScript needs to know the shapes of these libraries to check your code. That's where DefinitelyTyped and @types/ packages come in — they're the Nizam's Embassy Translators.

Analogy: The Nizam's Darbar receives foreign diplomats who speak only French, Japanese, or Arabic. The Nizam's court speaks only Urdu and Persian. Without a translator, nobody understands anyone! The embassy provides TRANSLATORS — people who know both languages.

@types/express is the translator for Express. @types/node is the translator for Node.js. The actual library (the foreign diplomat) speaks JavaScript. The translator (the @types package) provides TypeScript definitions so the Nizam's court (your TS code) can communicate properly.

Without the translator, TypeScript just sees any — the diplomat is mumbling incomprehensibly. With the translator, TypeScript understands every word! This is crucial because modern web development relies heavily on third-party packages. Without type definitions, you lose all the safety and autocompletion benefits that TypeScript provides. You'd be writing TypeScript syntax but effectively dealing with JavaScript's dynamic chaos. The @types/ ecosystem ensures that even if the original library author didn't write TypeScript, the community has stepped in to provide the translation layer needed for a safe, productive coding experience.

02DefinitelyTyped & @types

DefinitelyTyped is the massive community repository of type definitions for thousands of JavaScript libraries. The packages are published under the @types/ scope on npm.

Installing type definitions:

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

After installation, TypeScript AUTOMATICALLY finds these types in node_modules/@types/. You don't need to import them manually.

The structure:

node_modules/
  @types/
    express/
      index.d.ts
    node/
      index.d.ts

Some libraries INCLUDE their own types (bundled types): React, Zod, Axios — no @types/ needed because the types are shipped with the package itself in their package.json "types" or "typings" field.

How to check:

// In the library's package.json
{
  "name": "zod",
  "types": "./lib/index.d.ts",
  // If "types" exists, it's bundled!
  // No @types/zod needed.
}

If the "types" field is absent, you need @types/library-name. If you run npm install @types/nonexistent, you'll get a 404 error because no types exist.

Controlling inclusion in tsconfig:

{
  "compilerOptions": {
    // Only include these @types
    "types": ["node", "express"]
  }
}

By default, ALL @types in node_modules are included. Use the types field to explicitly control which ones are included, which is very useful for frontend projects that shouldn't accidentally import Node.js globals.

03When Types Don't Exist

What to do when there are no bundled types AND no @types package? Three options depending on how much type safety you need.

Option 1: Quick Declaration (Any)

// types/untyped-lib.d.ts
declare module "untyped-lib";

Creates a module with any types. Quick but unsafe.

import lib from "untyped-lib";
// No errors, but no type safety
lib.anything();

Option 2: Write Your Own .d.ts (Safe)

// types/untyped-lib.d.ts
declare module "untyped-lib" {
  export function init(
    config: { key: string }
  ): void;
  export const version: string;
}

More work but fully type-safe. Best for production code where you want autocomplete and error checking.

Option 3: Use Any (Escape Hatch)

// When you're in a hurry
const lib: any = require("untyped-lib");

You can contribute your types back to DefinitelyTyped — it's open source and community-maintained! Your contribution helps thousands of other developers.

Custom type roots:

// tsconfig.json
{
  "compilerOptions": {
    "typeRoots": [
      "./node_modules/@types",
      "./custom-types"
    ]
  }
}

The typeRoots option tells TypeScript to also look in your custom-types folder for declarations, allowing you to organize your custom type definitions neatly.

04Third-party Types Traps

Working with third-party types has its own set of pitfalls. Let's make sure you avoid these common traps!

Trap 1: Version Mismatch

// Node 16 installed
npm install node@16
// But types for Node 18!
npm install -D @types/node@18

The types might not match the runtime version. Always try to match major versions to ensure API compatibility.

Trap 2: Types are WRONG sometimes

DefinitelyTyped is community-maintained, and types can have bugs. If a type is incorrect, you can use module augmentation to fix it:

// fix-express.d.ts
declare module "express" {
  export function fixed(
    x: string
  ): number;
}

Trap 3: Orphaned @types packages

You uninstall a library but forget its @types package. The types linger and can cause confusion. Clean up your devDependencies!

Trap 4: Global pollution

// Some @types add globals
// @types/node adds Buffer, process
// Bad for frontend projects!

In frontend projects, this is wrong — you don't want Node.js globals in browser code. Use "types": [] in tsconfig to prevent auto-inclusion, then explicitly list what you need.

Trap 5: Conflicts between @types

Different @types packages might depend on each other and require compatible versions. Use npm's peer dependency warnings to catch this early and resolve version conflicts.

05Third-party Types Cheatsheet

Here's your quick-reference cheatsheet for third-party types — pin it to your mental dashboard and refer back whenever you need it!

Bundled types: Library ships its own .d.ts — no install needed. Check: package.json has "types" field.
@types packages: Community-maintained — npm install -D @types/libname. Auto-discovered in node_modules/@types.
No types available:
- declare module "lib" — quick any
- Write custom .d.ts — proper types
- Use any — escape hatch
tsconfig controls: "types": ["node"] — explicitly control which @types to include. "typeRoots": [...] — custom type locations.

// Check for bundled types
// library/package.json
{
  "types": "./lib/index.d.ts"
}

// Install community types
npm i -D @types/express

// Quick declare for untyped lib
declare module "my-untyped-lib";

// Custom declaration
declare module "my-lib" {
  export function run(): void;
}

Key rules:

Check for bundled types first
Install matching @types versions
Write your own types when none exist
Contribute back to DefinitelyTyped
Clean up orphaned @types packages

The Golden Rule: @types packages are the Nizam's embassy translators — they help TypeScript understand the foreign JavaScript diplomats. Always check for translators before inviting the diplomat into the darbar, bhai!

Key Takeaways

@types packages provide TypeScript definitions for JavaScript libraries
DefinitelyTyped is the community repo; install via npm install -D @types/libname
Some libraries bundle their own types — check package.json for the "types" field
Use declare module to quickly type untyped libraries, or write custom .d.ts files for safety
Match @types package versions with your installed library versions to avoid mismatch bugs

Previous8.3 — Ambient Types & .d.ts 📋 All Chapters Next Chapter8.5 — Namespace vs Modules →