Frontend Engineering | VoidX Academy

18. Declaration Files & External Libraries

Bridging the Gap with JavaScript

TypeScript is great when you write it from scratch. But the NPM ecosystem is full of millions of libraries written in plain, old JavaScript. If you import a plain JS library, the TypeScript compiler has no idea what functions it contains, and will throw errors. Declaration Files (.d.ts) act as a translator between untyped JS and strict TS.

What is a .d.ts file?

A declaration file ends in .d.ts. It contains zero implementation code (no logic, no math, no console logs). It solely contains type definitions (Interfaces, Types, and function signatures) that describe an external JavaScript file.

Using DefinitelyTyped (@types)

For famous libraries like `lodash` or `react`, the community has already written massive declaration files. You simply download them as dev dependencies.

# Install the untyped JavaScript library
npm install lodash

# Install the community-written TypeScript declarations for it
npm install -D @types/lodash

Writing Custom Declarations (`declare module`)

If you use an obscure, small library that doesn't have `@types` available, you must write a custom declaration file to stop the compiler from complaining. You do this using declare module.

// Create a file named 'custom-lib.d.ts' in your project

// We tell TypeScript: "Hey, a module named 'obscure-js-library' exists."
declare module "obscure-js-library" {
  // Inside, we define the functions it exports and their types
  export function calculateLegacyMath(a: number, b: number): number;
  export const libraryVersion: string;
}

// Now, in your App.ts, you can import it safely without TS errors!
// import { calculateLegacyMath } from 'obscure-js-library';

Declaring Global Variables

Sometimes scripts loaded in the <head> of your HTML (like Google Analytics) add variables directly to the global window object. TypeScript doesn't know they exist. You must declare them globally.

// In a global.d.ts file
declare global {
  interface Window {
    // Tells TS that window.gtag exists and is a function
    gtag: (...args: any[]) => void; 
  }
}

// Now TS allows this:
// window.gtag('event', 'login');

18. Declaration Files & External Libraries

Bridging the Gap with JavaScript

What is a .d.ts file?

Using DefinitelyTyped (@types)

For famous libraries like `lodash` or `react`, the community has already written massive declaration files. You simply download them as dev dependencies.

# Install the untyped JavaScript library
npm install lodash

# Install the community-written TypeScript declarations for it
npm install -D @types/lodash

Writing Custom Declarations (`declare module`)

If you use an obscure, small library that doesn't have `@types` available, you must write a custom declaration file to stop the compiler from complaining. You do this using declare module.

// Create a file named 'custom-lib.d.ts' in your project

// We tell TypeScript: "Hey, a module named 'obscure-js-library' exists."
declare module "obscure-js-library" {
  // Inside, we define the functions it exports and their types
  export function calculateLegacyMath(a: number, b: number): number;
  export const libraryVersion: string;
}

// Now, in your App.ts, you can import it safely without TS errors!
// import { calculateLegacyMath } from 'obscure-js-library';

Declaring Global Variables

Sometimes scripts loaded in the <head> of your HTML (like Google Analytics) add variables directly to the global window object. TypeScript doesn't know they exist. You must declare them globally.

// In a global.d.ts file
declare global {
  interface Window {
    // Tells TS that window.gtag exists and is a function
    gtag: (...args: any[]) => void; 
  }
}

// Now TS allows this:
// window.gtag('event', 'login');

18. Declaration Files & External Libraries

Bridging the Gap with JavaScript

What is a .d.ts file?

Using DefinitelyTyped (@types)

Writing Custom Declarations (`declare module`)

Declaring Global Variables

Knowledge Check

18. Declaration Files & External Libraries

Bridging the Gap with JavaScript

What is a .d.ts file?

Using DefinitelyTyped (@types)

Writing Custom Declarations (`declare module`)

Declaring Global Variables

Knowledge Check