Modules, tsconfig and Projects

Introduction

So far every example was a single file. Real projects have many, and they need a place to say how strict the compiler should be. This lesson shows how files share code, and how a project is configured. The code samples here are shown for reading and are not runnable in the browser editors, because they need several files.

Modules: splitting code into files

Any file that has a top-level import or export is a module. It has its own scope. Things are private unless exported.

// shapes.ts
export interface Point {
  x: number;
  y: number;
}

export function distance(a: Point, b: Point): number {
  return Math.hypot(a.x - b.x, a.y - b.y);
}

const secret = 42; // not exported, so private to this file

// main.ts
import { distance, type Point } from "./shapes";

const a: Point = { x: 0, y: 0 };
const b: Point = { x: 3, y: 4 };
console.log(distance(a, b)); // 5

• export makes a value or type available to other files.
• import { ... } from "./file" brings it in. Note there is no .ts ending in the path.
• export default and import name from also exist, but named exports are easier to rename and search for.

import type

Types do not exist at runtime, so importing one only matters to the compiler. Mark it with type, as with type Point above, or import a whole line:

import type { Point } from "./shapes";

This makes it clear nothing is needed at runtime, and the compiler removes the line from the output entirely.

tsconfig.json

A project has a tsconfig.json file at its root. It tells the compiler which files to include and how strictly to check them. Here is a typical small one:

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "strict": true,
    "noUncheckedIndexedAccess": true,
    "skipLibCheck": true,
    "outDir": "dist"
  },
  "include": ["src"]
}

• target: which JavaScript version to produce.
• module and moduleResolution: how imports are written and found.
• strict: turns on a group of safety checks (see below).
• outDir: where compiled JavaScript goes.
• include: which folders to compile.

Run the compiler with npx tsc. Add --noEmit to only check types without producing files, which is what many projects do when another tool builds the code.

Strict mode

"strict": true is shorthand for a family of checks. The ones you have met are:

• noImplicitAny: errors when TypeScript would silently fall back to any.
• strictNullChecks: null and undefined are separate types you must handle.
• strictFunctionTypes and strictPropertyInitialization: stricter rules for functions and class fields.

Start new projects with strict on. Turning it on later in a large codebase is painful. noUncheckedIndexedAccess goes further: reading array[0] gives T | undefined, because the index might not exist.

Declaration files and @types

JavaScript libraries do not carry types. A declaration file (ending .d.ts) describes the types of JavaScript code, with no implementation.

// legacy.d.ts
declare function legacyAdd(a: number, b: number): number;

Many libraries ship their own .d.ts files. For popular ones that do not, the community maintains types on DefinitelyTyped, installed as separate packages:

npm install --save-dev @types/node

Now import fs from "node:fs" is fully typed. If TypeScript says it "could not find a declaration file for module", look for an @types/... package.

Try it yourself

This program compiles in the editor, but it crashes when it runs, because the array is empty. In a project with noUncheckedIndexedAccess on, TypeScript would flag the last line, since first is string | undefined. Fix the program with a check, so that it prints no names yet instead of crashing.

Summary

• A file with a top-level import or export is a module. Anything not exported stays private.
• import type marks imports that exist only for the compiler.
• tsconfig.json sets target, module system, strictness and which files to compile. Run npx tsc.
• Turn strict on for new projects. .d.ts files and @types packages describe untyped JavaScript.