Skip to content

Declaration Files (.d.ts)

Describe JavaScript libraries with .d.ts declaration files and the declare keyword.

What you'll learn

  • What .d.ts files are and why they contain no implementation
  • Using the declare keyword for ambient declarations
  • How @types packages provide types for JS libraries
  • Writing custom declarations for untyped modules

Concept

Ambient Declarations

A declaration file (.d.ts) contains type declarations only — no runtime code. It describes the types of an existing JavaScript library so TypeScript can type-check code that uses it. The declare keyword tells the compiler "this exists at runtime, trust me" without generating any JavaScript. For example, declare const VERSION: string; tells TypeScript a global VERSION constant exists without emitting code for it.

@types Packages

Most popular JavaScript libraries have community-maintained type definitions published as @types/library packages on npm (via the DefinitelyTyped repository). You install them with npm install --save-dev @types/lodash and TypeScript automatically finds them. If a library ships its own types (look for a types or typings field in package.json), you do not need a separate @types package.

Writing Custom Declarations

When a library has no types and no @types package, you can write a custom declaration. Create a .d.ts file and declare the module: declare module "my-lib" { export function doSomething(x: string): number; }. For global variables, use declare global { interface Window { myVar: string; } }. Custom declarations bridge the gap between typed TypeScript code and untyped JavaScript libraries.

Example

              // --- globals.d.ts — ambient declarations (no runtime code) ---

// Declare a global variable that exists at runtime.
declare const APP_VERSION: string;

// Declare a global function.
declare function legacyFormat(date: Date): string;

// Augment the Window interface with a custom property.
declare global {
  interface Window {
    myAnalytics: (event: string) => void;
  }
}

// Declare an untyped module.
declare module "legacy-lib" {
  export function parse(input: string): Record<string, unknown>;
  export const version: string;
}

// --- main.ts — using the declarations ---
// These exist at runtime (injected by a script tag or the environment).
console.log(APP_VERSION);
console.log(legacyFormat(new Date()));
window.myAnalytics("page_view");

// import { parse } from "legacy-lib";
// const data = parse('{"x":1}');
            

Declaration files (.d.ts) describe types without implementation. The declare keyword asserts runtime existence. @types packages provide types for JS libraries. Custom declarations handle untyped modules and global variables.

Try it

  • JSON to TypeScript

    Generated interfaces can serve as the basis for declaration files.

  • Code Minifier

    Declaration files compile to nothing — observe the empty output.

Common mistakes

The mistake

Putting runtime code in a .d.ts declaration file

The fix

Declaration files contain types only — no implementations. If you need runtime code, use a regular .ts file. The compiler does not emit JavaScript from .d.ts files.

The mistake

Not installing @types packages for JavaScript dependencies

The fix

Check if a @types/package exists for every JS library you use. Without it, the library is typed as any, losing all type safety for that dependency.

Look up unfamiliar terms

A beginner-friendly glossary explains jargon in plain English — variables, functions, DOM, Promise, and more.

View glossary

Build real projects

Apply what you learned by building guided projects with starter code and solutions.

View projects

Decode error messages

Plain-English explanations of common errors — what they mean, why they happen, and how to fix them.

View errors