Course contentsShow
← TypeScript
Lesson 1598 of 1,79637. Migrating JavaScript to TypeScriptFree lesson

Creating .d.ts Stubs for Dependencies

Write declaration files for untyped third-party libraries to unblock migration progress.

Creating .d.ts Stubs for Dependencies

What you'll learn: How to write minimal declaration files for untyped third-party libraries so your migration can continue without getting blocked.

The Migration Blocker Problem

When gradually migrating a JavaScript project to TypeScript, you'll inevitably encounter third-party dependencies that don't have type definitions. Without types, TypeScript treats these imports as any, which defeats the purpose of migration—or worse, it blocks your progress entirely when noImplicitAny is enabled.

Creating .d.ts stubs is your escape hatch: minimal type declarations that unblock your migration without requiring you to fully type someone else's library.

What Is a Stub Declaration File?

A stub is a bare-minimum .d.ts file that declares just enough about a module to satisfy the TypeScript compiler. Think of it as a placeholder sign that says "this module exists and exports something"—you're not documenting every detail, just enough to move forward.

For an untyped package like some-old-library, you'd create src/types/some-old-library.d.ts:

declare module 'some-old-library' {
  const content: any;
  export default content;
}

This tells TypeScript: "Yes, this module exists. It exports something as any. Stop complaining."

Refining Stubs Incrementally

Once unblocked, you can refine the stub over time as you learn what the library actually exports:

declare module 'some-old-library' {
  export function doSomething(input: string): void;
  export const VERSION: string;
}

You don't need perfection—just enough accuracy for the parts of the library your code actually uses.

Where to Place Stub Files

Convention: create a types/ or @types/ directory in your project root, then reference it in tsconfig.json:

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

Now TypeScript will discover your custom stubs alongside official @types packages.

Key Takeaway: Stub .d.ts files let you unblock migration progress for untyped dependencies with minimal effort—start with any, refine as you go, and keep moving forward.