Declaration Files

Recipe

Create and manage .d.ts declaration files for global types, module augmentation, untyped third-party packages, and custom ambient declarations in a React/Next.js project.

Working Example

// types/global.d.ts - Global type declarations
type User = {
  id: string;
  name: string;
  email: string;
  role: "admin" | "editor" | "viewer";
};
 
type ApiResponse<T> = {
  data: T;
  meta: {
    page: number;
    totalPages: number;
  };
};

// types/environment.d.ts - Typed environment variables
declare namespace NodeJS {
  interface ProcessEnv {
    NODE_ENV: "development" | "production" | "test";
    DATABASE_URL: string;
    NEXT_PUBLIC_API_URL: string;
    NEXT_PUBLIC_SITE_URL: string;
    AUTH_SECRET: string;
  }
}

// types/modules.d.ts - Declaring untyped modules
declare module "some-untyped-library" {
  export function doSomething(input: string): Promise<string>;
  export function configure(options: { verbose: boolean }): void;
}
 
// Asset imports
declare module "*.svg" {
  const content: React.FC<React.SVGProps<SVGSVGElement>>;
  export default content;
}
 
declare module "*.png" {
  const src: string;
  export default src;
}
 
declare module "*.css" {
  const classes: Record<string, string>;
  export default classes;
}

Deep Dive

How It Works

• .d.ts files are declaration files that contain only type information, no runtime code. They tell TypeScript about types that exist at runtime but are not expressed in TypeScript source.
• Files in a types/ directory are included automatically if your tsconfig.json has "include": ["**/*.ts", "**/*.tsx"] or if the path matches an include pattern.
• Ambient declarations (declare) tell TypeScript "this exists at runtime, trust me." Use them for global variables, untyped modules, and environment extensions.
• Module augmentation extends existing module types using declare module "module-name". This is how you add fields to ProcessEnv, extend Next.js types, or patch third-party library types.
• TypeScript resolves types in this order: local source files, paths mappings, node_modules/@types/*, then custom .d.ts files in include-matched directories.

Variations

Augmenting Next.js types:

// types/next-auth.d.ts - Extending next-auth session types
import { DefaultSession } from "next-auth";
 
declare module "next-auth" {
  interface Session {
    user: {
      id: string;
      role: "admin" | "editor" | "viewer";
    } & DefaultSession["user"];
  }
}

Extending Window:

// types/window.d.ts
declare global {
  interface Window {
    analytics: {
      track: (event: string, properties?: Record<string, unknown>) => void;
      identify: (userId: string) => void;
    };
    __ENV__: Record<string, string>;
  }
}
 
export {}; // Required to make this a module

Typed CSS Modules:

// types/css-modules.d.ts
declare module "*.module.css" {
  const classes: { readonly [key: string]: string };
  export default classes;
}
 
declare module "*.module.scss" {
  const classes: { readonly [key: string]: string };
  export default classes;
}

Creating a global utility type:

// types/utils.d.ts
type Prettify<T> = {
  [K in keyof T]: T[K];
} & {};
 
type StrictOmit<T, K extends keyof T> = Pick<T, Exclude<keyof T, K>>;
 
type Nullable<T> = T | null;

TypeScript Notes

• Declaration files with declare global { } modify the global scope. The file must have at least one import or export to be treated as a module; add export {} if needed.
• declare module "x" augments a module. If the module already has types, your declarations are merged. If it does not, your declaration replaces the implicit any.
• Do not put implementation code in .d.ts files. They are erased during compilation and serve only as type hints.
• Use typeRoots in tsconfig.json to control where TypeScript looks for declaration files: "typeRoots": ["./types", "./node_modules/@types"].

Gotchas

• Forgetting export {} in a file with declare global makes the file a script (not a module), and its declarations may not merge correctly.
• Ambient module declarations (declare module "x") replace the module's types entirely unless you import from the module first. To augment, add an import statement.
• @types/* packages from DefinitelyTyped can conflict with bundled types in newer package versions. Check if the library ships its own types before installing @types/.
• skipLibCheck: true skips type-checking all .d.ts files, including yours. Errors in your custom declarations will be silently ignored.
• Environment variable types (ProcessEnv) provide compile-time confidence but no runtime guarantee. The variable could still be missing at runtime. Always validate at startup.

Alternatives

FAQs

// types/environment.d.ts
declare namespace NodeJS {
  interface ProcessEnv {
    NODE_ENV: "development" | "production" | "test";
    DATABASE_URL: string;
    NEXT_PUBLIC_API_URL: string;
  }
}

// types/modules.d.ts
declare module "some-untyped-library" {
  export function doSomething(input: string): Promise<string>;
  export function configure(options: { verbose: boolean }): void;
}

declare module "*.svg" {
  const content: React.FC<React.SVGProps<SVGSVGElement>>;
  export default content;
}
 
declare module "*.png" {
  const src: string;
  export default src;
}

// types/window.d.ts
declare global {
  interface Window {
    analytics: {
      track: (event: string) => void;
    };
  }
}
export {};

Related

• TypeScript Basics
• Strict Mode Patterns
• Typing API Responses
• Utility Types