TypeScript: TypeScript Declaration Files

// Usage lodash —— A pure JavaScript library
import _ from "lodash";

// ❌ TypeScript Error: Module not found "lodash" Statement Document
let result = _.chunk([1, 2, 3, 4], 2);

// lodash.d.ts —— Statement（Describe only the type，No implementation provided）
declare module "lodash" {
  export function chunk<T>(array: T[], size: number): T[][];
  export function debounce(func: Function, wait: number): Function;
  // ... Additional Statements
}

# Check if a package has @types Statement
npm info @types/lodash

# Installation Type Declaration
npm install @types/lodash --save-dev

// After installing @types/lodash — full type support
import _ from "lodash";

let chunks: number[][] = _.chunk([1, 2, 3, 4], 2);  // ✅ Type Safety
let debounced = _.debounce(() => {}, 300);            // ✅ Auto-Complete

// globals.d.ts
declare var jQuery: (selector: string) => HTMLElement;
declare var $: typeof jQuery;

// Usage
let el = $(".container");  // ✅ Type Safety

// globals.d.ts
declare function ga(command: string, ...args: any[]): void;
declare function gtag(type: string, eventName: string, params?: Record<string, any>): void;

// Usage
ga("send", "pageview");               // ✅
gtag("event", "click", { value: 1 });  // ✅

// declarations.d.ts
declare module "untyped-lib" {
  export function doSomething(value: string): number;
  export const version: string;
  export default class Client {
    constructor(options: { host: string; port: number });
    connect(): Promise<void>;
  }
}

// Usage
import Client, { doSomething, version } from "untyped-lib";

// Extend the built-in Array interface
declare module "./types" {
  interface Entity {
    id: number;
  }
}

10
30

// Suppose there is a legacy-utils.js The file has no type
// legacy-utils.d.ts —— Write a statement for it

declare module "legacy-utils" {
  /**
   * Format the date according to the specified pattern
   * @param date - Date object or timestamp
   * @param pattern - Format patterns, e.g. "YYYY-MM-DD"
   */
  export function formatDate(date: Date | number, pattern: string): string;

  /**
   * Deep-copy objects
   */
  export function deepClone<T>(obj: T): T;

  /**
   * Image Stabilization Function
   */
  export function debounce<T extends (...args: any[]) => any>(
    fn: T,
    delay: number
  ): (...args: Parameters<T>) => void;

  /**
   * Default Export：Toolset Object
   */
  const utils: {
    formatDate: typeof formatDate;
    deepClone: typeof deepClone;
    debounce: typeof debounce;
  };

  export default utils;
}

// Usage——Full Type Support
import utils from "legacy-utils";

let dateStr = utils.formatDate(new Date(), "YYYY-MM-DD");
let cloned = utils.deepClone({ name: "Charlie" });
let debounced = utils.debounce((x: number) => console.log(x), 300);

No runtime output — demonstrates declaration file usage

// ── Global Declarations（None import/export） ──
// All declarations in the file are automatically visible throughout the entire project.
declare var GLOBAL_CONFIG: { api: string };
declare function globalHelper(): void;

// ── Module Declaration ──
declare module "my-lib" {
  export function helper(): void;
}

// ── File Module Declaration ──
// At the top of the document, there is import/export → The entire file is a module
import { User } from "./types";
export declare function processUser(user: User): void;

// ✅ Recommendations——Export Interfaces and Types
export interface User {
  id: number;
  name: string;
}

export type UserId = number;

// ✅ Recommendations——Exported Function Signatures
export declare function getUser(id: number): User;

// ❌ Not recommended——Export the specific implementation（.d.ts Should not be implemented）
// export function getUser(id: number): User { return ...; }

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

{
  "compilerOptions": {
    "types": ["node", "jest", "lodash"]
    // Includes only these three @types packages, ignoring the rest
  }
}

{
  "compilerOptions": {
    "noImplicitAny": true,          // Implicit is prohibited any
    "strict": true,                  // Enable all strict checks
    "skipLibCheck": true             // Skip .d.ts File Type Validation（Speed up compilation）
  }
}

10
30

// env.d.ts — declare global constants and types
declare var APP_VERSION: string;
declare var API_BASE_URL: string;

interface AppWindow extends Window {
  appConfig: {
    theme: "light" | "dark";
    locale: string;
  };
}

// Usage in any .ts file
console.log(`v${APP_VERSION}`);
console.log(APP_VERSION);

10
30

10
30

// array-ext.d.ts — add a method to the built-in Array type
interface Array<T> {
  last(): T | undefined;
  first(): T | undefined;
}

// Now every array has .last() and .first() with full type safety
let items = [10, 20, 30];
let first = items.first();   // number | undefined
let last = items.last();     // number | undefined

console.log(first);  // 10
console.log(last);   // 30

10
30