Modules & Declaration Files

An import in a TypeScript file can bring in two very different kinds of thing. Values — functions, classes, constants — exist at runtime, so the import has to survive into the JavaScript. Types — interfaces, type aliases — exist only while the compiler is checking. After type erasure there is nothing left to import, so the import has to disappear. The compiler has to decide, import by import, which is which.

By default tsc decides using import elision: it looks at how each imported name is used in the file, and if a name is only ever used in type positions, it drops it from the output. If every name in an import statement is dropped, the whole statement goes. That works when tsc compiles the whole project, because it can open ./user.ts and see that User is an interface. It does not work for tools that compile one file at a time — esbuild, swc, Babel, Vite and Node's built-in type stripping. Looking at import { User } from "./user.js" on its own, they can't tell whether User is a class (keep it) or an interface (delete it).

import type solves this by labelling the import. Think of the types as the paperwork that travels with a delivery: the compiler reads it, checks everything against it, and then shreds it before the truck (the JavaScript) leaves. import type stamps "paperwork" on the box, so any tool can shred it without opening it.

import type { IncomingMessage, ServerResponse } from "node:http";
import { createServer, type Server } from "node:http";

function handle(req: IncomingMessage, res: ServerResponse): void {
  res.end(`You asked for ${req.url}`);
}

const server: Server = createServer(handle);

import type { Server } from "node:http";

let s: Server;                     // fine: a type annotation
type ServerClass = typeof Server;  // fine: a type query is still a type position
const created = new Server();      // ❌ TS1361: 'Server' cannot be used as a value because it was imported using 'import type'.

export interface User { id: number; name: string }
export type Role = "admin" | "user";

console.log("user.ts loaded"); // a side effect at the top level

import type { User } from "./user.js";
import { type Role } from "./user.js";

const u: User = { id: 1, name: "Ann" };
const r: Role = "admin";
console.log(u.name, r);

const u = { id: 1, name: "Ann" };
const r = "admin";
console.log(u.name, r);
export {};

import {} from "./user.js";
const u = { id: 1, name: "Ann" };
const r = "admin";
console.log(u.name, r);

From my notes: .d.ts files are purely type definition files that describe the types and signatures of objects, functions and classes without providing the implementation. They let TypeScript understand the shape of a module implemented in JavaScript — a contract between your TypeScript code and existing JavaScript.

The mental model is a C header file, or the menu in a restaurant: the menu lists every dish and what it comes with, but there's no food on it. The compiler reads only the menu; the kitchen (the .js file) is what actually runs. A .d.ts file can contain types, interfaces and signatures — but no function bodies, no initial values, no statements. It never produces any JavaScript.

You meet .d.ts files in three ways: libraries ship them next to their compiled .js (generated by tsc --declaration), @types/* packages provide them for libraries that don't (see @types packages), and you write them yourself for JavaScript you can't or don't want to convert.

Here is the example from my notes — a plain CommonJS JavaScript module:

function add(a, b) {
  return a + b;
}
function multiply(a, b) {
  return a * b;
}
module.exports = { add, multiply };

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

import { add, multiply } from "./utils.js";

console.log(add(2, 3), multiply(2, 3)); // 5 6
add("2", 3); // ❌ TS2345: Argument of type 'string' is not assignable to parameter of type 'number'.

declare module "utils" {
  export function add(a: number, b: number): number;
  export function multiply(a: number, b: number): number;
}

export function add(a: number, b: number) {
  return a + b;
}
export const PI = 3.14159;
export interface Point { x: number; y: number }
export class Vec {
  #hidden = 1;
  constructor(public x: number, private secret = 0) {}
  len() { return Math.abs(this.x); }
}
const internal = "not exported";

export declare function add(a: number, b: number): number;
export declare const PI = 3.14159;
export interface Point {
    x: number;
    y: number;
}
export declare class Vec {
    #private;
    x: number;
    private secret;
    constructor(x: number, secret?: number);
    len(): number;
}

The declare keyword says: "this exists at runtime — someone else created it — here is its type. Emit nothing." A declaration with declare is called an ambient declaration: it describes something without implementing it. Everything in a .d.ts file is ambient automatically; in a .ts file you add declare by hand.

You need it whenever a value appears at runtime without your TypeScript code creating it: a global set by a <script> tag (Google Analytics' gtag), a constant your bundler replaces at build time (Vite's define, webpack's DefinePlugin), or a variable injected by the host environment. Without a declaration, the compiler only sees a name that was never defined.

declare const __APP_VERSION__: string; // replaced by the bundler at build time
declare function gtag(command: "event", name: string, params?: Record<string, unknown>): void;
declare class Analytics {
  constructor(writeKey: string);
  track(event: string, props?: Record<string, unknown>): void;
}

console.log(`v${__APP_VERSION__}`);
gtag("event", "signup", { plan: "pro" });
new Analytics("wk_123").track("page_view");

declare let retries: number = 3;         // ❌ TS1039: Initializers are not allowed in ambient contexts.
declare function reset(): void {}        // ❌ TS1183: An implementation cannot be declared in ambient contexts.
declare const MAX_RETRIES = 3;           // allowed: a const with a literal records the literal type 3

From my notes: many popular libraries already have type definitions available via @types. For example, to use lodash: npm install lodash @types/lodash.

Some libraries are written in TypeScript or ship hand-written declarations, and their package.json points at them ("types", or a "types" condition in "exports"). Many older libraries are plain JavaScript and ship no types at all. For those, the community maintains DefinitelyTyped, a huge GitHub repository of declaration files, and publishes each one to npm under the @types scope: the types for lodash are @types/lodash. Scoped packages get a double underscore: @babel/core → @types/babel__core.

The mental model: the library is the product, @types/x is the third-party manual. It's written by different people, versioned separately, and can drift. By convention its major and minor version follow the library's (@types/lodash@4.17.x describes lodash@4.17), so match them when you install.

import { chunk, debounce } from "lodash";

const pages = chunk([1, 2, 3, 4, 5], 2); // number[][] → [[1, 2], [3, 4], [5]]
const save = debounce((text: string) => console.log("saving", text), 300);
save("draft");

{
  "compilerOptions": {
    "types": ["node"]
  }
}

Sometimes a package has no types anywhere — no "types" field, no @types package. Under strict (specifically noImplicitAny), importing it is an error:

error TS7016: Could not find a declaration file for module 'slugify-lite'.
'/app/node_modules/slugify-lite/index.js' implicitly has an 'any' type.

declare module "legacy-charts";

import { drawChart } from "legacy-charts";

drawChart("#sales", { anything: "goes" }); // compiles: drawChart is any

declare module "slugify-lite" {
  export interface SlugifyOptions {
    lower?: boolean;
    separator?: string;
  }
  export function slugify(input: string, options?: SlugifyOptions): string;
}

import { slugify, type SlugifyOptions } from "slugify-lite";

const options: SlugifyOptions = { lower: true, separator: "_" };
const id: string = slugify("Hello World", options);
slugify(42); // ❌ TS2345: Argument of type 'number' is not assignable to parameter of type 'string'.

declare module "pad-left-lite" {
  function padLeft(input: string, width: number, fill?: string): string;
  namespace padLeft {
    const version: string;
  }
  export = padLeft;
}

import padLeft from "pad-left-lite";

padLeft("7", 3, "0");                // "007"
padLeft.version.toUpperCase();

declare module "*.svg" {
  const url: string;
  export default url;
}

import logoUrl from "./logo.svg";

const img = document.createElement("img");
img.src = logoUrl; // string

The global scope in TypeScript is made of every script file in the program — every file with no top-level import or export — plus the built-in lib files (lib.dom.d.ts declares interface Window, document, and so on). A declaration at the top level of a script file is global. A declaration in a module file is local to that module.

That creates a puzzle. You often want to add a global — a property on window set by an analytics script, or a config object injected into the page — from a file that is a module, because it imports a type. In a module, a top-level interface Window { … } declares a new, local Window that has nothing to do with the global one. declare global { … } is the way out: it reaches from inside a module back into the global scope. Everything inside it is merged into the globals, using declaration merging.

export {}; // makes this file a module — required for `declare global`

declare global {
  interface Window {
    analytics?: { track(event: string, props?: Record<string, unknown>): void };
  }
  var __APP_CONFIG__: { apiUrl: string; release: string };
  let buildNumber: number;
}

window.analytics?.track("page_view");

console.log(__APP_CONFIG__.apiUrl);
console.log(window.__APP_CONFIG__.release);
console.log(globalThis.buildNumber); // ❌ TS2339: Property 'buildNumber' does not exist on type 'typeof globalThis'.

globals.d.ts(1,9): error TS2669: Augmentations for the global scope can only be directly nested in external modules or ambient module declarations.
main.ts(1,8): error TS2339: Property 'analytics' does not exist on type 'Window & typeof globalThis'.

interface Window {
  buildId: string;
}
declare const BUILD_TIME: string;

Module augmentation adds declarations to a module that already has types — a package's own types, @types/*, or one of your own modules. You re-open the module with declare module "name" { … } from a file that is itself a module, and the compiler merges what you write into the existing declarations. It's declaration merging across files: interfaces from both places combine into one.

The typical reason is that a library has an extension point the library author couldn't know how you'd use. Express middleware attaches req.user; a React app uses CSS custom properties in style; a plugin adds a method to a library's class. The library's types are correct, just incomplete for your app.

Here is a real one that works with @types/react 19. By default, style doesn't accept CSS custom properties: style={{ "--accent": accent }} fails with TS2353 "Object literal may only specify known properties, and '"--accent"' does not exist in type 'Properties<string | number, string & {}>'."

import "react";

declare module "react" {
  interface CSSProperties {
    [customProperty: `--${string}`]: string | number;
  }
}

export function Badge({ accent }: { accent: string }) {
  return <span style={{ "--accent": accent, color: "var(--accent)" }}>New</span>;
}

import type { Role } from "../auth/roles.js";

declare global {
  namespace Express {
    interface Request {
      user?: { id: string; role: Role };
    }
  }
}

import express from "express";
const router = express.Router();

router.get("/me", (req, res) => {
  if (!req.user) {
    res.status(401).json({ error: "Not signed in" });
    return;
  }
  res.json({ id: req.user.id, role: req.user.role });
});

Both use the same syntax — declare module "name" { … } — and do opposite things. Which one you get depends on one fact about the file it's written in: is the file a module?

A way to remember it: a script file is talking about the world, so declare module introduces a module to the world. A module file is talking about itself and its imports, so declare module patches one of its imports.

declare module "tiny-router" {
  interface RouteMeta {
    requiresAuth?: boolean;
  }
}

From my notes: namespaces were used before ES6 to keep related code together. Before JavaScript had modules, every script shared one global scope. TypeScript's answer (originally called "internal modules") was the namespace: a named block whose exported members become properties of one global object, while everything else stays private inside it — the JavaScript IIFE module pattern, with compiler support.

namespace Utils {
  export function add(a: number, b: number): number {
    return a + b;
  }
  export function subtract(a: number, b: number): number {
    return a - b;
  }
  const secret = 42; // not exported → private to the namespace
}

console.log(Utils.add(10, 5)); // 15
console.log(Utils.subtract(10, 5)); // 5

var Utils;
(function (Utils) {
    function add(a, b) {
        return a + b;
    }
    Utils.add = add;
    function subtract(a, b) {
        return a - b;
    }
    Utils.subtract = subtract;
    const secret = 42;
})(Utils || (Utils = {}));
console.log(Utils.add(10, 5));
console.log(Utils.subtract(10, 5));

function formatPrice(cents: number, options?: formatPrice.Options): string {
  const currency = options?.currency ?? "CAD";
  return `${(cents / 100).toFixed(2)} ${currency}`;
}
namespace formatPrice {
  export interface Options {
    currency?: "CAD" | "USD" | "EUR";
  }
}

const opts: formatPrice.Options = { currency: "USD" };
formatPrice(1999, opts); // "19.99 USD"

module Legacy { export const x = 1; } // ❌ TS1540: A 'namespace' declaration should not be declared using the 'module' keyword. Please use the 'namespace' keyword instead.

They solve the same problem — keeping code organised without polluting the global scope — in two different eras. A namespace is a TypeScript feature that builds one global object at runtime. A module is a JavaScript feature: each file is its own scope, and you connect files with import/export. Modules won, and the TypeScript handbook itself says to prefer them for new code.

The rows that matter most in practice:

1. Dependencies: with namespaces, file b.ts can use Utils.add from a.ts only if a.ts runs first, and nothing in b.ts says so. With modules, import { add } from "./a.js" states the dependency, and the loader orders everything.
2. Bundling: Utils is one object, so a bundler can't tell which members you use and keeps them all. Separate named exports can be dropped individually.
3. Tooling: Node's type stripping rejects value namespaces outright, and single-file compilers like esbuild and swc can't merge a namespace that is split across files — the reasons erasableSyntaxOnly exists.
4. Where namespaces are still right: in declaration files, to group types or describe a global object. @types/node puts ProcessEnv in namespace NodeJS; Express's extension point is namespace Express; React's JSX types live in namespace React.JSX. These are declare namespaces — types only, nothing emitted.
5. A UMD library's .d.ts ends with export as namespace MyLib;, which says "when this file is loaded with a plain <script> tag, the same exports are available as the global MyLib". That is the one bridge between the two worlds.