Modules & Declaration Files

A module is a single file that uses export to share specific values and types and import to pull them into other files, while a declaration file ( .d.ts ) supplies type information for code that already exists without emitting any runtime JavaScript.

Learn Modules & Declaration Files in our free TypeScript course — an interactive lesson with runnable examples, a practice exercise and a quick reference.

Part of the free TypeScript course at LearnCodingFast — hands-on lessons with examples you run in your browser, plus practice exercises and a quick quiz.

What You'll Learn

💡 Real-World Analogy

A module is a shop with a storefront and a stockroom . The items on display (your export s) are what customers can buy; everything in the back (un-exported helpers) is private and stays out of sight. An import is a customer walking in and taking a specific labelled item off the shelf. A barrel file is a shopping mall directory that lists where to find products from several shops in one place. A .d.ts declaration file is the price-and-spec sheet for goods made in another factory: it tells you exactly what each item is, even though it wasn't manufactured here.

1. Exports, Imports & the Public Surface

Each file is its own scope. Whatever you mark with export becomes visible to other files; everything else stays private to that file. You then bring names in with import . Here is real TypeScript module syntax across two files:

The runnable box uses the module pattern to show the same public/private split inside one file.

2. Default vs Named Exports & Re-exports

A module can have at most one export default plus any number of named exports. The default is imported under a name you choose; named exports keep their names (or are aliased with as ). A barrel file re-exports several modules so consumers import from one path:

3. Type-Only Imports & Declaration Files

import type brings in something used purely as a type and is erased completely from the output — zero runtime cost, no circular-import surprises. A .d.ts file uses declare to describe code that already exists at runtime (a global, a plain-JS library) so the compiler can type-check against it:

🔎 Deep Dive: Module Resolution Basics

When you write import x from "..." , TypeScript has to find the file. The specifier tells it how:

• Relative ( "./utils" , "../lib/date" ) — resolved against the current file's folder. These are your files.
• Bare / package ( "react" , "lodash" ) — looked up in node_modules , using the package's types / exports fields (or a matching @types/* package).
• Path aliases ( "@/components/Button" ) — custom prefixes mapped in tsconfig.json under paths (this project uses @/ for src/ ).

The moduleResolution compiler option (commonly "bundler" or "node16" ) controls the exact lookup rules — you'll meet it in the next lesson on tsconfig .

🎯 Your Turn

Build a small string-utilities module with the module pattern: return the functions you want to "export" and list the public surface. Fill in the blanks and match the expected output.

Common Errors (and the fix)

• ❌ "Module has no exported member 'X'": you forgot export on the declaration, or imported the wrong name. ✅ Add export , or check spelling/casing of the imported name.
• ❌ Default vs named mix-up: import { createUser } when the file used export default fails. ✅ Import a default without braces: import createUser from "./user" .
• ❌ "Cannot find module 'foo' or its type declarations": the package ships no types. ✅ Install @types/foo , or add a declare module "foo"; stub in a .d.ts .
• ❌ Accidental global script: a file with no imports/exports leaks names globally and may clash. ✅ Add an export {} to force module scope.
• ❌ Type imported as a value: importing an interface and trying to use it at runtime fails — it doesn't exist after compilation. ✅ Use import type and only reference it in type positions.

Pro Tips

• 💡 Default to named exports. They refactor and tree-shake better; reserve export default for a file's single main export.
• 💡 Mark type-only imports with import type (or inline { type X } ) to keep them out of the runtime bundle.
• 💡 Keep barrels small. A giant index.ts re-exporting everything can hurt tree-shaking and invite circular imports.
• 💡 Reach for @types/* first when a JS library lacks types; write your own .d.ts only when none exists.

Frequently Asked Questions

Mini-Challenge: Counter Module

Build a counter "module" that keeps its count private and exposes only increment , decrement , and value — exactly the encapsulation a real module file provides. Follow the outline, run it, and match the example output.

🎉 Lesson Complete

• ✅ export defines a file's public surface; everything else stays private
• ✅ One export default per file plus any number of named exports
• ✅ import type brings in types and is fully erased at compile time
• ✅ Barrel files ( index.ts ) re-export modules from one path
• ✅ .d.ts files use declare to type existing code with no runtime output
• ✅ Specifiers resolve relatively, from node_modules , or via tsconfig path aliases
• ✅ Next lesson: tsconfig & Compiler Options

Practice quiz

Continue this course

• Previous: Discriminated Unions
• Next: tsconfig & Compiler Options