Complete Guide to Declaring Third-Party Modules in TypeScript: Compatibility Solutions from CommonJS to ES Modules

Core Challenges in Third-Party Module Declaration

In the TypeScript ecosystem, developers frequently encounter module declaration issues when working with third-party JavaScript libraries. Particularly when these libraries are written using the CommonJS specification, their export mechanisms fundamentally differ from the ES6 module system, leading to type checking failures. This article examines a typical scenario: a third-party module exports via module.exports = function foo() { ... }, while developers attempt to import it using import * as foo from 'foo-module', resulting in a "cannot find declaration module" error.

Analysis of Module System Differences

The ES6 module system and CommonJS module system have fundamental differences in their export mechanisms. ES6 modules require explicit export statements such as export function foo() or export default function foo(), while CommonJS's module.exports allows replacing the entire module with a single value. This discrepancy necessitates additional declaration information for TypeScript's type inference.

Modern Solutions in TypeScript 2.7+

Starting with TypeScript 2.7, the introduction of the esModuleInterop compiler option has fundamentally changed how CommonJS modules are handled. This option allows TypeScript to interpret non-ES6-compatible export patterns more flexibly.

First, enable this option in tsconfig.json:

{
  "compilerOptions": {
    "esModuleInterop": true
  }
}

Then create the declaration file foo-module.d.ts:

declare module "foo-module" {
  function foo(): void;
  export = foo;
}

Now you can safely use two import approaches:

// Approach 1: Namespace import
import * as foo from "foo-module";
foo();

// Approach 2: Default import
import foo from "foo-module";
foo();

Historical Compatibility Solutions

Before TypeScript 2.7, a special "namespace hack" was required to handle this situation:

declare module "foo-module" {
  function foo(): void;
  namespace foo { } // Key to enabling ES6 wildcard imports
  export = foo;
}

The corresponding import syntax also differed:

// ES6-style import
import * as foo from "foo-module";
foo();

// CommonJS-style import
import foo = require("foo-module");
foo();

Best Practices for Declaration Files

Creating high-quality declaration files requires adherence to several key principles:

1. Accurately describe the module's export structure, including function signatures, parameter types, and return types

2. Consider the module's actual usage scenarios and provide the most intuitive import methods

3. Maintain synchronization between declaration files and source module versions

4. Fully leverage TypeScript's type system to provide as detailed type information as possible

Practical Application Recommendations

For new projects, strongly consider enabling the esModuleInterop option, as this aligns with modern JavaScript ecosystem trends. For maintaining legacy projects, choose appropriate declaration strategies based on the TypeScript version. When encountering complex third-party modules, refer to the declaration file templates in the official TypeScript documentation, which cover various common module patterns.

Understanding module system differences is not only crucial for solving technical problems but also foundational for building maintainable, type-safe TypeScript projects. Through proper declaration strategies, developers can seamlessly integrate various JavaScript libraries while enjoying the type safety benefits provided by TypeScript.