Core Code
Core Code Modern Dev Handbook

External Libraries

Learn how to safely integrate external JavaScript libraries into TypeScript projects. This guide covers type definitions, unknown boundaries, module resolution, and maintaining type safety across third-party dependencies.
On this page

Why external libraries are a risk boundary

Every third-party dependency is a boundary where type safety can break. Libraries may have incomplete type definitions, incorrect typings, or no types at all. In production systems, you must treat external libraries as partially untrusted and integrate them carefully.

Installing libraries with built-in types

Many modern libraries ship with their own TypeScript definitions.

npm install axios

If the package includes types, TypeScript will automatically detect them.

Libraries without types

If a package does not provide types, TypeScript will treat it as any unless you define types yourself. This removes safety and should be handled intentionally.

Using @types packages

Many community-maintained type definitions are available via DefinitelyTyped.

npm install --save-dev @types/lodash

This restores type safety for libraries that do not ship their own types.

Creating minimal declaration files

If no type definitions exist, create a custom declaration file.

declare module "legacy-lib" {
  export function doSomething(input: string): number;
}

Place this in a .d.ts file inside your project.

Using unknown at integration boundaries

When consuming external APIs or loosely typed libraries, treat return values as unknown and narrow them safely.

async function fetchData(): Promise {
  const res = await fetch("/api/data");
  return res.json();
}

Validate and narrow before using the data.

Module system compatibility

Some libraries use CommonJS, others use ES Modules. Ensure your tsconfig.json matches your runtime environment.

{
  "compilerOptions": {
    "module": "CommonJS",
    "esModuleInterop": true
  }
}

Avoiding implicit any leaks

Never allow missing types to silently become any. This can spread unsafely throughout your codebase. If necessary, wrap external libraries in typed adapter functions.

Adapter pattern for safety

Create a thin wrapper around external dependencies and expose a well-typed internal API.

import axios from "axios";

type User = { id: number; name: string };

export async function getUsers(): Promise {
  const res = await axios.get("/api/users");
  return res.data as User[];
}

This isolates unsafe assertions inside a single controlled location.

Common mistakes

  • Using any to silence missing type errors.
  • Trusting external API responses without validation.
  • Mixing module systems incorrectly.
  • Spreading loosely typed values deep into the application.

Production guidance

  • Prefer libraries that ship official TypeScript definitions.
  • Install @types packages when needed.
  • Wrap unsafe libraries behind typed adapters.
  • Validate external data at boundaries.
  • Keep strict mode enabled.

What’s next

Next, we will explore DefinitelyTyped in detail and understand how community-maintained type definitions work in real-world projects.

DefinitelyTyped →