Command Palette

Search for a command to run...

Hectal
Phase 11Intermediate12 of 18 in TypeScript

Modules and Declaration Files

Split code into files with import and export, learn how the compiler finds files, read and write .d.ts files, type third-party code and check plain JavaScript.

Real projects are many files, not one. This phase is about what happens between files: how import and export work in TypeScript, how the compiler decides which file an import points to (module resolution), and how it learns the types of code that is not written in TypeScript at all.

You'll meet declaration files (.d.ts), the files that hold only types. They are how npm packages ship their types, how @types/* packages type old JavaScript libraries, and how you describe things that exist at runtime but that TypeScript did not create (a script tag that adds window.analytics, an environment variable the bundler replaces). You'll also learn to extend existing types (declare global, module augmentation) and to type-check plain .js files with JSDoc comments.

The live editor on this site is one file, so imports between files can't run there. Where an example needs several files, the page shows real files from a small project built for this course and the real output of tsc (TypeScript 7.0.2) run on it. Everything that fits in one file (declare, declare global, namespaces, JSDoc) is a live example you can edit.

0/6 · 0%
6 topics ~2 h 25 code blocks & diagrams
Start with the first topic
1
11.1

Modules in TypeScript

A module is a file that has its own import or export, so its names stay private until you export them. TypeScript checks imports and exports the same way JavaScript runs them, with extra rules (import type, verbatimModuleSyntax, isolatedModules) that keep type-only code from leaking into the output.

22 min 4 code practice

2
11.2

Module Resolution

Module resolution is how the compiler turns the text in import "./util" or import "shapes" into a real file. The module and moduleResolution settings pick the rulebook: nodenext copies Node.js, bundler copies Vite and webpack, and preserve leaves your imports alone.

23 min 4 code practice

3
11.3

Declaration Files (.d.ts)

A declaration file (.d.ts) holds only types and declare statements, no running code. It describes what a JavaScript file or a global offers, so TypeScript can check code that uses it. tsc can write them for you with declaration, and isolatedDeclarations makes that fast.

22 min 4 code practice

4
11.4

Typing Third-Party Code

Most npm packages are JavaScript, so TypeScript needs their types from somewhere: bundled inside the package, from a @types/* package, or from a short declare module you write yourself. Since TypeScript 6 you also choose which global @types load, with the types option.

21 min 4 code practice

5
11.5

Globals, Namespaces and Module Augmentation

Some names live everywhere (window, process, a bundler constant). declare global, interface merging and module augmentation let you add to existing types safely, and namespaces are the old way to group code that modules replaced.

22 min 6 code practice

6
11.6

Type-Checking JavaScript

TypeScript can check plain .js files too. With allowJs and checkJs (or // @ts-check in one file) it reads types from JSDoc comments, so you can add safety to an old JavaScript project one file at a time, without renaming anything.

22 min 3 code practice

Practise this phase

Hands-on exercises: write the code, see your page live, and press Check to have it tested automatically.

1

Teach Window about your theme

A script on your page sets window.theme. TypeScript doesn't know Window has that property. Teach it, with a type that only allows "light" or "dark".

Beginner
2

Merge two interfaces

Account is declared once with id. The code below creates an account with a balance too, which the checker rejects.

Beginner
3

Add last() to every array

Make [1, 2, 3].last() work and type-check. Add the type with declare global and interface Array<T>: last() returns the last item, or undefined for an empty array (T | undefined).

Intermediate
4

Make these exports isolatedDeclarations-safe

This example turns on isolatedDeclarations, so every export must carry written types where one file alone can't infer them. Three exports fail. Add the types they need.

Intermediate
5

A typed global config

A build tool puts a global __CONFIG__ object on the page. Declare its type in declare global with var: apiUrl: string, retries: number, features: readonly string[].

Intermediate