TypeScript Tricks

Modules

TS Ambient Modules

Using Ambient Modules

TypeScript ambient modules declare types for external JavaScript code.

What are Ambient Modules?

Ambient modules in TypeScript are a way to describe the shape of modules that exist elsewhere, such as in JavaScript libraries where TypeScript type information is not available. They allow developers to use these libraries with type safety and IntelliSense in their TypeScript projects.

Declaring an Ambient Module

To declare an ambient module, you use the declare module syntax. This is useful when you want to use a JavaScript library that does not have its own TypeScript definitions. You create a .d.ts file, which stands for 'definition file', and write the module declaration inside it.

Here's a basic example of how to declare an ambient module:

Using Ambient Modules

Once you've declared an ambient module, you can use it in your TypeScript code like any other module. TypeScript will provide type checking and IntelliSense support based on the definitions you've provided.

For example, using the module declared above:

Benefits of Using Ambient Modules

Ambient modules are particularly useful when working with JavaScript libraries that do not have TypeScript support. By declaring your own type definitions, you gain several advantages:

  • Type Safety: You get compile-time checking of your code, reducing runtime errors.
  • IntelliSense: Enhanced editor support with code completion and inline documentation.
  • Documentation: Your type definitions serve as documentation for how to use the library.

Common Use Cases

Ambient modules are often used in the following scenarios:

  • Integrating with JavaScript libraries that do not provide TypeScript definitions.
  • Working in a codebase with a mix of JavaScript and TypeScript files.
  • Creating type definitions for legacy libraries where official types are not available.

Modules

Next
Module Augmentation