Declaration Files (.d.ts)

After this lesson, you will be able to: Read DefinitelyTyped declarations and write your own .d.ts for untyped libraries.

Declaration files are how JS-only libs get TS support. Most you'll use; some you'll write.

Prerequisites:TypeScript with Node.js

DefinitelyTyped: the @types ecosystem

DefinitelyTyped is a community-maintained repo of types for popular JS libraries. Install via `npm install --save-dev @types/express`. Imported automatically by tsc when present. Many modern libs ship their own types now (zod, react, vite). Check `package.json` for `"types": "./dist/index.d.ts"`.

Writing your own .d.ts

For libraries without types (or for ambient declarations).

tsx

// types/untyped-lib.d.ts
declare module "untyped-lib" {
  export function format(value: string): string;
  export function parse(input: string): { ok: boolean; data: unknown };
  export const VERSION: string;
}

// Or augment global types
declare global {
  interface Window {
    myCustomAPI: { call(): void };
  }
  namespace NodeJS {
    interface ProcessEnv {
      DATABASE_URL: string;
      JWT_SECRET: string;
    }
  }
}
export {};   // marks file as a module

Triple-slash directives (legacy)

Older approach; modern use ESM imports.

tsx

/// <reference path="./types/global.d.ts" />
/// <reference types="node" />

// Modern equivalent in tsconfig.json:
// "types": ["node", "vitest/globals"]
// "include": ["src/**/*", "types/**/*"]

Common mistakes only experienced TS devs avoid

Writing declarations for libs that already have built-in types. Check first. Wide types (any, unknown) in declarations. Be specific where you can. Forgetting `export {};` in global augmentations. Without it, declare global isn't recognised. Maintaining stale .d.ts when the library updates. PR back to DefinitelyTyped instead of forking locally.

Quick Check

What's `declare module "foo"` for?

Pick the cleanest answer.

←TypeScript with Node.js + Express/Fastify

Back to TypeScript

Decorators, Metadata, and NestJS→