Modules & Declaration Files

TypeScript's module syntax is exactly ECMAScript's import/export — nothing new to learn there. What TypeScript adds is checked at the boundary: the type checker verifies that what a file imports matches what the other file actually exports, and a separate form, import type, imports only a type with zero runtime trace.

export interface Point {
  x: number
  y: number
}

export function distance(a: Point, b: Point): number {
  return Math.sqrt((a.x - b.x) ** 2 + (a.y - b.y) ** 2)
}

export const ORIGIN: Point = { x: 0, y: 0 }

// A default export — one per file, imported without braces
export default function midpoint(a: Point, b: Point): Point {
  return { x: (a.x + b.x) / 2, y: (a.y + b.y) / 2 }
}

import midpoint, { distance, ORIGIN, type Point } from "./math"
// ^ default        ^ named            ^ type-only named import

const here: Point = { x: 3, y: 4 }
console.log(distance(here, ORIGIN))
console.log(midpoint(here, ORIGIN))

// Import everything as one namespace object
import * as MathUtils from "./math"
MathUtils.distance(here, ORIGIN)

// Re-export: this file did not define Point, but other files can import it from here
export { type Point } from "./math"

A .d.ts file contains only type declarations — signatures, interfaces, shapes — never an implementation. It compiles to nothing; nothing is ever emitted from it. Its job is to describe code that already exists somewhere as plain JavaScript, so the compiler can check the calls you make into it without ever reading that JavaScript itself.

// The actual, runnable implementation — plain JavaScript, no types
export function greet(name, punctuation) {
  return "Hello, " + name + (punctuation || "!")
}

// The type description that sits next to it — no function BODY, only its shape
export function greet(name: string, punctuation?: string): string

• Hand-written — you write the .d.ts yourself next to a plain .js file you own or vendored.
• Generated — tsc --declaration produces one automatically from your own .ts source; this is how most published TypeScript packages ship types.
• Published separately — the community writes and maintains one on DefinitelyTyped, installed as an @types/ package (next lesson).

declare tells the compiler "trust me, this exists at runtime" without generating any code for it — no variable is created, no function is defined. It is for exactly one situation: something is available when your code runs, but TypeScript has no way to see where it came from, because it was not created by an import in this project — a <script> tag, a bundler-injected constant, a test runner global.

// index.html has:  <script src="https://cdn.example.com/ga.js"></script>
// which defines window.gtag before this file ever runs. TypeScript never
// sees that <script> tag, so without the line below, "gtag" is a
// ReferenceError-in-waiting the compiler cannot warn you about — worse,
// it is a hard TS2304 "Cannot find name" until you tell it gtag exists.
declare const gtag: (...args: unknown[]) => void

gtag("event", "purchase", { value: 49 })

// Augmenting an existing global type instead of a bare const — this adds a
// property to the ambient Window interface everyone already has
declare global {
  interface Window {
    gtag: (...args: unknown[]) => void
  }
}

export {}   // required: this line is what makes the file a MODULE, so
            // "declare global" augments the shared global scope rather
            // than silently declaring one more separate global scope

declare

A type-only statement: describes a binding for the checker without creating it. Erased completely on compile.

Ambient declaration

Any declaration made with declare — "ambient" because it describes something already present in the ambient (surrounding) environment.

Global augmentation

declare global { ... } — adds to the shared global type scope (like Window) from inside a module file.

The same idea, applied to a whole module specifier instead of one global: declare module "some-specifier" tells TypeScript "when something imports this string, here is what it gets" — without TypeScript ever reading that module's actual source. This covers two cases: an npm package with no types anywhere, and a non-JavaScript import your bundler handles (an .svg, a .css module) that has no types by definition.

// This package ships no types, and no @types/my-lib exists on npm
declare module "my-lib" {
  export function process(input: string): string
  export const VERSION: string
}

// Anywhere else in the project, this now compiles — with real autocomplete
import { process, VERSION } from "my-lib"

// A wildcard ambient module — matches ANY specifier ending in .svg.
// Bundlers (webpack, Vite) turn an .svg import into a URL string at build
// time; TypeScript has no idea unless you tell it, once, project-wide.
declare module "*.svg" {
  const src: string
  export default src
}

// now this compiles everywhere in the project
import logo from "./logo.svg"

Most popular JavaScript libraries were never written in TypeScript, so their types live in a separate, community-maintained project: DefinitelyTyped. Its packages are published to npm under the @types/ scope — @types/lodash, @types/react, @types/node — and TypeScript automatically discovers anything installed under node_modules/@types, with no import or config needed to wire it up.

{
  "name": "slugify-lite",
  "main": "dist/index.js",
  "types": "dist/index.d.ts",
  "devDependencies": {
    "@types/node": "^22.0.0"
  }
}

Type-checking an import "./thing" requires TypeScript to first turn that string into a real file, the same way Node or a bundler eventually will at runtime. moduleResolution in tsconfig picks which of those algorithms the checker mimics — get it wrong and you get errors that only exist in the editor, or worse, code that compiles clean and then fails to actually run.

{
  "compilerOptions": {
    "moduleResolution": "bundler",
    "baseUrl": ".",
    "paths": {
      "@/*": ["./src/*"]
    }
  }
}

paths lets you write import { Task } from "@/types" instead of "../../../types". It only ever remaps the specifier for the compiler and your editor — tsc does not rewrite @/* into a real relative path in the JavaScript it emits. Whatever actually runs the output — Node directly, or a bundler — has to be told the same mapping separately.