What `declare` Means in TypeScript

By the end of this page, you will understand what declare means in TypeScript, why it is used for type-only information, and how it differs from normal declarations. You will also see where it appears in .d.ts files, when it is useful in real projects, and what mistakes beginners commonly make.

declare tells TypeScript:

• This thing exists somewhere else
• Use this information for type checking
• Do not generate JavaScript for it

TypeScript has two jobs:

• check types while you write code
• compile to JavaScript

Normally, when you write code, TypeScript may emit JavaScript output. But sometimes you want to describe something that already exists at runtime, such as:

• a global variable loaded by another script
• a function provided by a library
• types from an external JavaScript package
• browser or environment-specific globals

That is where declare is used.

For a type alias like this:

type Callback = (err: Error | string, data: Array<CalledBackData>) => void;

type already exists only in TypeScript's type system. It does not produce JavaScript anyway. So adding declare here usually does not change runtime behavior.

   =  ;

Think of declare as a label on a box you are not allowed to open.

TypeScript is told:

• "Trust me, this box exists"
• "Here is what is inside, at least from a typing point of view"
• "Do not try to build the box yourself"

Without declare, you usually provide the real thing:

const VERSION = "1.0.0";

With declare, you only describe it:

declare const VERSION: string;

So:

• normal declaration = description + implementation
• declare declaration = description only

For type, there is no runtime implementation anyway, so declare type is mostly about saying "this type is being declared for type purposes only," which is often redundant outside declaration-file contexts.

The declare keyword can be used with several kinds of declarations.

Common syntax

declare const appName: string;
declare let currentUserId: number;
declare function fetchUser(id: number): Promise<string>;
declare class Logger {
  log(message: string): void;
}

These tell TypeScript about values that exist somewhere else.

Example: external global variable

Imagine a script tag loads a library that creates a global variable named analytics.

declare const analytics: {
  track(eventName: string): void;
};

analytics.track();

Consider this example:

declare const API_URL: string;

function buildUrl(path: string) {
  return API_URL + path;
}

const result = buildUrl("/users");

Here is what happens step by step:

1. TypeScript reads:

   declare const API_URL: string;
   

   It records that a constant named API_URL exists and that its type is string.

2. TypeScript does not expect an implementation here. There is no assigned value like:

   const API_URL = "https://example.com";
   

3. In buildUrl, TypeScript allows string concatenation because API_URL is known to be a string.

declare is useful in several practical situations.

1. Typing global variables from external scripts

A script loaded in HTML might create a global:

declare const Stripe: {
  init(key: string): void;
};

This lets your TypeScript code use Stripe safely.

2. Writing or consuming .d.ts files

Libraries often ship declaration files that describe their API:

declare function formatDate(date: Date): string;

This helps TypeScript users get autocomplete and type safety even if the library itself is plain JavaScript.

3. Gradually adding TypeScript to a JavaScript project

If runtime values already exist, you can declare them while migrating:

declare const legacyConfig: {
  apiBase: ;
  : ;
};

In real projects, developers usually use declare in these patterns.

Declaration files

The most common place is a .d.ts file:

declare module "legacy-lib" {
  export function connect(url: string): void;
}

This tells TypeScript how to type a library.

Global augmentation

When a runtime global exists but TypeScript does not know about it:

declare global {
  interface Window {
    myAppVersion: string;
  }
}

Then elsewhere:

console.log(window.myAppVersion);

Bridging JavaScript and TypeScript

During migration, teams often keep JavaScript implementations and add TypeScript declarations around them.

API surface description

1. Thinking declare creates a real variable

Broken expectation:

declare const apiKey: string;
console.log(apiKey);

This compiles, but if apiKey does not actually exist at runtime, your program will fail.

Avoid this by using declare only for values provided elsewhere.

2. Using declare when you should write a real implementation

Incorrect:

declare function add(a: number, b: number): number;

If you are implementing the function yourself, write:

function add(a: number, b: number): number {
   a + b;
}

// Type alias
type Callback = (err: Error | string, data: CalledBackData[]) => void;

// Declared value provided elsewhere
declare const API_URL: string;

// Declared function provided elsewhere
declare function fetchData(id: number): Promise<string>;

// Declared class provided elsewhere
declare class Client {
  get(url: string): Promise<string>;
}

Key rules

• declare means: this exists elsewhere; use it for type checking
• declare does not create runtime code
• type and interface are already type-only

What does declare do in TypeScript?

It tells TypeScript that a variable, function, class, or other entity exists somewhere else and should be used only for type checking.

Does declare generate JavaScript code?

No. Declarations marked with declare are removed during compilation.

When should I use declare in TypeScript?

Use it when the real implementation is external, such as a global script, a JavaScript library, or a declaration file.

Is declare type necessary?

Usually no. A type alias is already type-only, so declare type is often redundant in regular .ts files.

What is an ambient declaration?

An ambient declaration is a declaration that describes something that exists at runtime but is defined elsewhere. declare is used for this.

Can declare cause runtime errors?

Yes. If you declare something that does not actually exist at runtime, TypeScript will be satisfied but JavaScript will fail.

Is declare mainly used in .d.ts files?

• type aliases - Related because declare type applies to type aliases.
• interfaces - Another way to describe shapes in TypeScript.
• declaration files (.d.ts) - The most common place where declare is used.
• ambient declarations - The formal idea behind describing values that exist elsewhere.
• global types - Useful when declaring global variables or extending built-in globals.
• modules - declare module is used to describe external packages.
• type erasure - Important because TypeScript types disappear at runtime.
• runtime vs compile time - Central to understanding why declare does not create values.