Deep Dive into TypeScript Declaration Files (*.d.ts): Concepts and Practical Applications

Fundamental Concepts of TypeScript Declaration Files

In the TypeScript ecosystem, *.d.ts declaration files play a crucial role. Similar to header files in C/C++, these files are specifically designed to describe type information for JavaScript code, but their working mechanisms differ significantly. The core value of declaration files lies in providing TypeScript type support for existing JavaScript libraries, allowing developers to benefit from static type checking without rewriting entire libraries.

Analysis of Three-File Relationships

Understanding the relationships between .js, .ts, and .d.ts files is essential for mastering declaration file usage. These three file types serve distinct purposes in a project:

.js files contain actual JavaScript code implementations responsible for runtime logic; .ts files are TypeScript source code containing type annotations and implementations; while .d.ts files contain only type declarations without concrete implementations. This separation design allows developers to add type support to existing JavaScript libraries without modifying the original code.

In practical projects, these three file types typically work together. For example, when importing a module, the TypeScript compiler automatically searches for corresponding declaration files:

src/
  my-module.js
  my-module.d.ts
  index.ts

In my-module.js:

const thing = 42;
module.exports = { thing };

The corresponding my-module.d.ts declaration file:

export declare const thing: number;

Usage in index.ts:

import { thing } from "./my-module";

// Runtime implementation comes from ".js" file
console.log(thing); // Output: 42

// Type declaration comes from ".d.ts" file
type TypeOfThing = typeof thing; // Type: number

Proper Usage of Declaration Files

Regarding whether *.ts files can be deleted and only *.d.ts files retained, it's important to distinguish between usage scenarios. For third-party JavaScript libraries, type support can indeed be provided through .d.ts files without needing .ts files. However, for self-developed TypeScript projects, .ts files contain actual implementations and cannot be simply replaced by declaration files.

Declaration files are primarily used in the following scenarios:

• Adding TypeScript type support to existing JavaScript libraries
• Describing types for pure JavaScript modules without TypeScript implementations
• Providing type definitions for external libraries without modifying original code

Module Mapping Mechanism

TypeScript associates declaration files with corresponding JavaScript files through specific resolution mechanisms. When importing a module, the compiler searches for declaration files in the following order:

1. Look for same-named .d.ts files in the same directory as the JavaScript file
2. Check type declaration paths in project configuration
3. Search for type definitions in the node_modules/@types directory

The key to this mapping mechanism is that TypeScript doesn't allow specifying file extensions in import statements. When importing ./my-module, the compiler automatically searches for my-module.js and my-module.d.ts, obtaining runtime implementation and type information respectively.

CommonJS Module Pattern Support

Declaration files support various module export patterns, particularly providing complete type description capabilities for CommonJS patterns. For CommonJS modules using module.exports:

const maxInterval = 12;
function getArrayLength(arr) {
  return arr.length;
}
module.exports = {
  getArrayLength,
  maxInterval,
};

The corresponding declaration file can be described as:

export function getArrayLength(arr: any[]): number;
export const maxInterval: 12;

For default export scenarios, declaration files use specific syntax:

// JavaScript
export default 3.142;

// Declaration file
declare const pi: number;
export = pi;

Application of Advanced Type Features

Declaration files support all of TypeScript's advanced type features, including generics, conditional types, and mapped types. This enables providing rich type information for JavaScript code:

export type ArrayMetadata<ArrType> = {
  length: number;
  firstObject: ArrType | undefined;
};

export function getArrayMetadata<ArrType>(arr: ArrType[]): ArrayMetadata<ArrType>;

Through generics, array element type information can propagate to the return type, providing more precise type inference.

Namespace Usage in Modules

When ES module syntax is insufficient to describe complex type relationships, namespaces can be used to organize type declarations:

export class API {
  constructor(baseURL: string);
  getInfo(opts: API.InfoRequest): API.InfoResponse;
}

declare namespace API {
  export interface InfoRequest {
    id: string;
  }
  export interface InfoResponse {
    width: number;
    height: number;
  }
}

This pattern allows organizing related types within namespaces, improving code readability and maintainability.

Practical Application Recommendations

In actual development, declaration file layout should mirror the corresponding JavaScript library structure. For libraries containing multiple modules:

myLib
+---- index.js
+---- foo.js
+---- bar
+---- index.js
+---- baz.js

The corresponding declaration file structure should be:

@types/myLib
+---- index.d.ts
+---- foo.d.ts
+---- bar
+---- index.d.ts
+---- baz.d.ts

This mirror structure ensures import paths align with declaration file paths, simplifying the type resolution process.

Testing and Validation

After creating declaration files, thorough testing is crucial. Type definition correctness can be verified through the following methods:

• Using declaration files to import modules in projects and checking for type errors
• Using TypeScript Playground to verify type inference results
• Creating specialized test cases to verify edge cases for complex libraries

Through systematic understanding and practice, developers can fully leverage the advantages of *.d.ts declaration files, enjoying the development efficiency improvements and code quality assurance brought by TypeScript static type checking while maintaining JavaScript runtime performance.