What are .d.ts files?

• Special files that contain only type information.
• Used to tell TypeScript about the shape of modules, globals, or libraries when TS cannot infer them.
• No JavaScript output – only used at compile time.

Module Declarations (declare module)

Used to describe the types of non-TS modules (e.g., .mdx, .svg, .png).

// mdx.d.ts
declare module "*.mdx" {
  const MDXContent: (props: any) => JSX.Element
  export default MDXContent
  export const metadata: import("@/types").PostMetadata
}

Example: allows import Post, { metadata } from "./hello.mdx" with proper types.

Global Declarations (declare global)

Adds types directly to the global scope so you don’t need to import.

// global.d.ts
declare global {
  type Metadata = import("@/types").PostMetadata

  interface Window {
    myGlobal: string
  }
}

Example: const x: Metadata = ... works anywhere without imports.

Module Augmentation

Extends or modifies the types of an existing library.

// express.d.ts
import "express"

declare module "express" {
  interface Request {
    user?: { id: string }
  }
}

Example: adds a user field to Express.Request.