Modern JavaScript applications routinely integrate numerous third-party libraries to fulfill various development requirements.

Regardless of whether these libraries were originally written in TypeScript, they ultimately compile down to JavaScript before being distributed to developers. TypeScript's type system enables valuable features like intelligent code completion and compile-time type checking.

When working with external libraries in TypeScript projects, you'll notice that most provide corresponding type definitions. This article explores how these types are sourced and how to leverage them effectively.

Distinguishing File Types in TypeScript

TypeScript projects involve two primary file extensions, each serving distinct purposes.

TypeScript Implementation Files (.ts)

Implementation files contain both type ennotations and executable code. These files get compiled into JavaScript and can be executed at runtime. They serve as the standard location for writing application logic.

interface Coordinate {
    lat: number;
    lng: number;
}

function calculateDistance(x1: number, y1: number, x2: number, y2: number): number {
    const deltaX = x2 - x1;
    const deltaY = y2 - y1;
    return Math.sqrt(deltaX * deltaX + deltaY * deltaY);
}

Type Declaration Files (.d.ts)

Declaration files exclusively contain type information without any executable implementation. The TypeScript compiler ignores these files during JavaScript generation—they exist solely to provide type definitions for other code.

interface Coordinate {
    lat: number;
    lng: number;
}

// Invalid: declaration files cannot contain implementations
function calculateDistance(x1: number, y1: number, x2: number, y2: number): number {
    return 0;
}

The fundamental distinction is straightforward: .ts files are implementation files containing runnable code, while .d.ts files are declaration files providing type information without implementations. When creating type definitions for existing JavaScript libraries, always use the .d.ts extension.

Working with Declaration Files

TypeScript offers several approaches for utilizing declaration files in your projects.

Built-in Declaration Files

TypeScript includes comprehensive type declarations for all standardized browser and Node.js APIs. When you work with native JavaScript types, you receive full autocomplete support and type safety.

Consider array operations—every array method comes with complete type information:

numbers.forEach((value: number, index: number) => {
    console.log(`Element at ${index}: ${value}`);
});

You can inspect these built-in definitions directly in your editor. On Windows and Linux, Ctrl+click (Cmd+click on macOS) on any standard API method navigates to its type declaration. The forEach method, for instance, is defined in lib.es5.d.ts.

Similarly, browser APIs like document and window have their definitions in lib.dom.d.ts:

const canvas = document.querySelector<HTMLCanvasElement>('#gameCanvas');
document.title = 'Game Started';

window.addEventListener('resize', () => {
    console.log(`New dimensions: ${window.innerWidth}x${window.innerHeight}`);
});

Third-Party Library Declarations

The TypeScript ecosystem provides type definitions for virtually every popular JavaScript library. These declarations arrive through two primary channels.

Libraries that bundle their own type definitions—such as Axios—require no additional configuration. Simply importing the library automatically loads its accompanying types, enabling full autocomplete support throughout your codebase.

For libraries without built-in types, the DefinitelyTyped repository serves as the authoritative source. This GitHub repository hosts high-quality TypeScript declarations for thousands of JavaScript libraries. You install these definitions using npm or yarn with packages prefixed by @types/:

npm install --save-dev @types/lodash
npm install --save-dev @types/react

When installed, TypeScript automatically discovers and incorporates these declaration packages. Modern editors like VS Code provide clear indicators when type declarations are missing, often suggesting the appropriate @types/* package to install.

Creating Custom Declaration Files

Sometimes you'll need to create your own type declarations, whether for sharing types across modules or providing definitions for legacy JavaScript code.

Sharing Types Within a Project

When multiple TypeScript files rely on identical type definitions, creating a centralized .d.ts file eliminates duplication and ensures consistency throughout your codebase.

Begin by establishing a declaration file that exports shared types:

// shared-types.d.ts
export interface ButtonProps {
    label: string;
    onClick: () => void;
    disabled?: boolean;
}

export type ThemeMode = 'light' | 'dark' | 'system';

Consume these types in any implementation file without specifying the extension:

// components/Header.ts
import { ButtonProps, ThemeMode } from '../shared-types';

const submitButton: ButtonProps = {
    label: 'Submit',
    onClick: () => console.log('Submitted'),
    disabled: false
};

let currentTheme: ThemeMode = 'light';

Declaring Types for Existing JavaScript

When migrating JavaScript projects to TypeScript or publishing libraries for others, you'll need to create declaration files for existing .js modules.

The declare keyword serves a specific purpose in type declarations: it announces the existence of variables, functions, or objects defined elsewhere (typically in JavaScript files) without creating new instances. This allows TypeScript's type checker to understand the shapes of existing runtime values.

Certain TypeScript-exclusive constructs like type, interface, and enum don't require the declare keyword since they exist purely in the type domain. However, runtime values that also exist in JavaScript—variables declared with let or const, and functions—should use declare to distinguish type declarations from actual implementations.

Consider a JavaScript utility module:

// mathUtils.js
const DEFAULT_PRECISION = 4;

function roundTo(value, decimals = 2) {
    const factor = Math.pow(10, decimals);
    return Math.round(value * factor) / factor;
}

function formatCurrency(amount, currency = 'USD') {
    return new Intl.NumberFormat('en-US', {
        style: 'currency',
        currency
    }).format(amount);
}

function validateEmail(email) {
    const pattern = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
    return pattern.test(email);
}

export { DEFAULT_PRECISION, roundTo, formatCurrency, validateEmail };

The corresponding declaration file would declare each exported entity with appropriate types:

// mathUtils.d.ts
declare const DEFAULT_PRECISION: number;

interface RoundOptions {
    decimals?: number;
}

declare function roundTo(value: number, options?: RoundOptions): number;

declare function formatCurrency(amount: number, currency?: string): string;

declare function validateEmail(email: string): boolean;

export { DEFAULT_PRECISION, roundTo, formatCurrency, validateEmail };

When TypeScript encounters imports from .js files, it automatically searches for corresponding .d.ts files in the same directory. This mechanism enables gradual type adoption in existing JavaScript codebases.

Recommended Learning Path

Master declaration files by first learning to consume existing types from built-in libraries and popular packages before creating your own type definitions for legacy JavaScript modules.