Typing third-party libraries in JavaScript & TypeScript

Typing third-party libraries

One of the trickiest moments in a TypeScript project arrives when you reach for a popular npm package and discover it has no type definitions. You install it, import it, and immediately see any everywhere—or worse, an error that tells you the module doesn't exist in TypeScript's eyes at all. Typing third-party libraries isn't just a nice-to-have; it's essential for keeping your codebase type-safe and maintainable. In this post, I'll walk through the practical strategies I use when packages don't ship types, from hunting down existing definitions to writing your own and even contributing them back to the community.

Check DefinitelyTyped — @types packages for many libraries

The first and easiest step is always to check whether someone has already solved the problem for you. DefinitelyTyped is a community-driven repository of TypeScript type definitions for JavaScript libraries that don't include their own. If a package has types on DefinitelyTyped, they're published under the @types namespace on npm.

Start by searching npm for @types/[package-name]. For example, if you're using lodash, you'd look for @types/lodash. If it exists, the installation is trivial:

npm install --save-dev @types/lodash

That's often all you need. Once installed, TypeScript will automatically pick up the types, and your imports work with full intellisense and type checking.

I've had excellent results with DefinitelyTyped for popular libraries like React, Express, Node.js, and countless others. The maintainers there are usually responsive, and the coverage is broad. A quick tip: if you're unsure whether types exist, check the official DefinitelyTyped website or use npm's search from the terminal. It's faster than guessing.

That said, not everything is on DefinitelyTyped. Newer packages, highly specialized libraries, or niche tools often have no community types yet. That's when you move to plan B: writing your own.

Write declarations — A small .d.ts file for the parts you use

When no @types package exists, I typically create a simple .d.ts file in my project. You don't need to type the entire library—just the parts you actually use. This is pragmatic and keeps the work manageable.

Let's say you're using a hypothetical package called color-picker that has no types. You're only using two functions: openPicker and parseColor. Create a file at the root of your project, maybe in a types folder:

// types/color-picker.d.ts

declare module 'color-picker' {
  export interface ColorResult {
    hex: string;
    rgb: [number, number, number];
    alpha: number;
  }

  export function openPicker(options: {
    defaultColor?: string;
    onSelect?: (color: ColorResult) => void;
  }): void;

  export function parseColor(input: string): ColorResult | null;
}

Now when you import from color-picker, TypeScript knows exactly what's available and what types to expect:

import { openPicker, parseColor } from 'color-picker';

const result = parseColor('#ff5733');
if (result) {
  console.log(result.hex); // TypeScript knows this is a string
}

Make sure your tsconfig.json includes this types folder. A typical configuration looks like:

{
  "compilerOptions": {
    "typeRoots": ["./node_modules/@types", "./types"]
  }
}

I've used this approach countless times when integrating smaller or internal packages. The effort is minimal compared to the type safety you gain. You're not committing to typing the entire library—only what you need today. As your usage expands, you can gradually add more types to the declaration file.

Module augmentation — Extend existing types, like adding user to Express requests

Sometimes the library already has types, but they don't quite fit your use case. You might want to attach custom properties to existing objects, or override behaviors for your specific application. Module augmentation lets you extend those types without modifying the original package.

A real-world example: I often use Express with TypeScript. Express has types, but the Request object doesn't know about custom properties you've added in middleware. If you set req.user in an authentication middleware, TypeScript will complain when you try to access it in a route handler.

Module augmentation solves this elegantly. Create a file like types/express.d.ts

// types/express.d.ts

import { Request } from 'express';

declare global {
  namespace Express {
    interface Request {
      user?: {
        id: string;
        email: string;
        role: 'admin' | 'user';
      };
    }
  }
}

export {};

app.get('/profile', (req, res) => {
  if (req.user) {
    console.log(req.user.email); // TypeScript is happy
    res.json({ userId: req.user.id });
  }
});