TypeScript Ambient Declarations
When working with TypeScript, you'll often need to use libraries that were written in JavaScript or don't have TypeScript definitions. This is where ambient declarations come in. They allow you to describe the shape of existing JavaScript code without modifying the original source, enabling TypeScript's type-checking system to understand external code.
What Are Ambient Declarations?
Ambient declarations are TypeScript's way of telling the compiler about the types of code that exists somewhere else. They're written in declaration files (.d.ts files) and don't contain implementations—only type information.
Think of ambient declarations as a contract between your TypeScript code and external JavaScript code, libraries, or global variables.
Declaration Files (.d.ts)
Declaration files use the extension .d.ts and contain only TypeScript type information without any actual implementation code.
Here's a basic structure of a declaration file:
// Example of a .d.ts file structure
declare module "module-name" {
export function someFunction(): void;
export class SomeClass {
constructor(param: string);
method(): number;
}
}
The declare Keyword
The declare keyword is central to ambient declarations. It tells TypeScript that a particular variable, function, class, or module exists somewhere in the runtime environment, even if it can't find it in your TypeScript files.
Common Uses of declare
Variables
// Declaring a global variable
declare const VERSION: string;
// Using the declared variable
console.log(`App version: ${VERSION}`);
Functions
// Declaring a global function
declare function log(message: string): void;
// Using the declared function
log("This is a message");
Classes
// Declaring a global class
declare class User {
name: string;
email: string;
login(): boolean;
}
// Using the declared class
const user = new User();
user.name = "John";
user.login();
Global vs. Module Declarations
TypeScript supports two main kinds of ambient declarations: global and module-based.
Global Declarations
Global declarations are available throughout your entire application without imports.
// myGlobals.d.ts
declare const PI: number;
declare function calculateCircumference(radius: number): number;
declare class MathHelper {
static random(): number;
}
With the above declarations, you can use these in any file:
// Using global declarations
const area = PI * radius * radius;
const circumference = calculateCircumference(radius);
const randomValue = MathHelper.random();
Module Declarations
Module declarations describe the shape of modules that need to be imported.
// lodash.d.ts
declare module 'lodash' {
export function chunk<T>(array: T[], size: number): T[][];
export function debounce(func: Function, wait: number): Function;
// ... other lodash methods
}
Then you can import and use it:
import { chunk, debounce } from 'lodash';
const chunks = chunk([1, 2, 3, 4], 2); // [[1, 2], [3, 4]]
const debouncedFn = debounce(() => console.log('Executed!'), 300);
Shorthand Ambient Module Declarations
For simple cases, you can use a shorthand syntax for declaring modules:
// shorthand.d.ts
declare module 'simple-library';
This tells TypeScript that the module exists but doesn't provide type information. Any imported values would be typed as any.
import anything from 'simple-library'; // Type of anything is 'any'
Working with Third-Party Libraries
Using DefinitelyTyped
Many popular libraries have type declarations available through the DefinitelyTyped repository, which can be installed using npm:
npm install --save-dev @types/library-name
For example, to add type definitions for jQuery:
npm install --save-dev @types/jquery
Once installed, you can use jQuery with proper TypeScript support:
import * as $ from 'jquery';
$(document).ready(() => {
$('.button').click(function() {
$(this).toggleClass('active');
});
});
Creating Your Own Declarations
If types aren't available for a library you're using, you can create your own declarations:
// my-library.d.ts
declare module 'my-library' {
export function doSomething(value: string): number;
export function processArray<T>(items: T[]): T[];
export interface Options {
debug?: boolean;
timeout?: number;
}
export default function initialize(options?: Options): void;
}
Then use it in your code:
import initialize, { doSomething, processArray } from 'my-library';
initialize({ debug: true });
const result = doSomething('test');
const processed = processArray([1, 2, 3]);
Ambient Namespaces
Just as you can declare ambient modules, you can also declare namespaces:
// jquery.d.ts
declare namespace $ {
function ajax(settings: any): void;
interface JQueryStatic {
get(url: string, callback?: (data: any) => void): void;
post(url: string, data: any, callback?: (data: any) => void): void;
}
}
// Using the namespace
$.ajax({ url: '/api/data' });
$.get('/api/data', (response) => {
console.log(response);
});
Advanced Example: Extending Global Objects
Sometimes you need to add properties to existing global objects. Here's how you can safely extend the Window interface:
// global-extensions.d.ts
interface Window {
customProperty: string;
customMethod(): void;
}
Now you can use these properties with type safety:
// The TypeScript compiler knows these exist now
window.customProperty = "Hello";
window.customMethod();
Real-World Example: Creating Declarations for a Chart Library
Let's say you're using a simple chart library that doesn't have TypeScript definitions. Here's how you might create types for it:
// simple-charts.d.ts
declare module 'simple-charts' {
export interface ChartOptions {
width?: number;
height?: number;
title?: string;
colors?: string[];
animate?: boolean;
}
export interface DataPoint {
label: string;
value: number;
}
export class PieChart {
constructor(element: HTMLElement | string, options?: ChartOptions);
setData(data: DataPoint[]): void;
render(): void;
on(event: 'click' | 'hover', callback: (point: DataPoint) => void): void;
}
export class BarChart {
constructor(element: HTMLElement | string, options?: ChartOptions);
setData(data: DataPoint[]): void;
render(): void;
}
export default {
PieChart,
BarChart
};
}
Now you can use this library with full TypeScript support:
import SimpleCharts, { PieChart, DataPoint } from 'simple-charts';
const salesData: DataPoint[] = [
{ label: 'Q1', value: 12000 },
{ label: 'Q2', value: 15000 },
{ label: 'Q3', value: 8000 },
{ label: 'Q4', value: 20000 }
];
// Create a pie chart
const chart = new PieChart('chart-container', {
width: 500,
height: 400,
title: 'Quarterly Sales',
colors: ['#ff6b6b', '#48dbfb', '#1dd1a1', '#f368e0'],
animate: true
});
chart.setData(salesData);
chart.render();
chart.on('click', (point) => {
console.log(`${point.label}: $${point.value}`);
});
Best Practices for Ambient Declarations
-
Be as specific as possible with types rather than using
any. -
Document your declarations with JSDoc comments for better developer experience.
-
Keep declarations focused - create separate files for different libraries or concepts.
-
Consider contributing your declarations back to DefinitelyTyped if they're for public libraries.
-
Name your files properly - use
module-name.d.tsfor module declarations. -
Use triple-slash references when needed to reference other declaration files:
/// <reference path="./other-declarations.d.ts" />
Debugging Ambient Declarations
Sometimes your declarations might not match the actual runtime behavior. When this happens:
- Check the actual JavaScript implementation
- Use console.log to verify behavior
- Consider using
anytemporarily until you understand the correct types - Use the
typeofoperator on runtime values to see their structure
Summary
Ambient declarations are a powerful feature of TypeScript that allows you to:
- Work with JavaScript libraries that don't have TypeScript definitions
- Define shapes for globals and modules that exist outside your TypeScript code
- Extend existing interfaces like Window or Document
- Create custom types for third-party code
They form the bridge between TypeScript's type system and the untyped JavaScript world, allowing you to leverage TypeScript's benefits even when working with plain JavaScript libraries.
Exercises
- Create a declaration file for a simple JavaScript utility library with 2-3 functions.
- Extend the Window interface to include properties used by a browser API like local storage.
- Write module declarations for a small npm package that doesn't have TypeScript definitions.
- Practice using the
@typespackages for a popular library like moment.js or lodash.
Additional Resources
If you spot any mistakes on this website, please let me know at [email protected]. I’d greatly appreciate your feedback! :)