Modules and Packages

As a program grows you split it across files and start pulling in packages written by other people. TypeScript uses the standard JavaScript module system, ES modules, and adds a way to share type information across those boundaries. This chapter covers import and export, npm packages and package.json, @types declaration packages, the module-related tsconfig options, and how to build.

import and export

Each file is its own module. Mark the values and types other files may use with export, and bring them in with import.

// src/math.ts
export const PI = 3.14159;

export function circleArea(radius: number): number {
  return PI * radius * radius;
}

export interface Range {
  min: number;
  max: number;
}

export default function clamp(value: number, range: Range): number {
  return Math.min(range.max, Math.max(range.min, value));
}

// src/index.ts
import clamp, { circleArea, PI } from "./math.js";
import type { Range } from "./math.js";
import * as math from "./math.js";

const range: Range = { min: 0, max: 10 };
console.log(clamp(15, range));      // 10
console.log(circleArea(2), PI);
console.log(math.circleArea(1));

A few details are worth calling out:

• Named exports are imported inside braces; a default export is imported without them. Named exports are generally preferred because the name is fixed, which keeps auto-imports and renames reliable.
• import type declares that only types are needed. It is erased completely from the output, so it never creates a runtime dependency.
• With module set to nodenext, relative imports need a file extension, and you write the extension of the compiled file, .js, even though the source is .ts. The compiler maps it back to the .ts file for you.

npm packages and package.json

package.json records your project's name, dependencies, and scripts. Packages needed at runtime belong in dependencies; tools used only during development belong in devDependencies.

npm install zod                 # runtime dependency
npm install --save-dev vitest   # development tool
npm install                     # install everything listed in package.json
npm outdated                    # see which packages have newer versions

{
  "name": "hello-ts",
  "type": "module",
  "main": "dist/index.js",
  "scripts": {
    "build": "tsc",
    "test": "vitest"
  }
}

"type": "module" tells Node.js to treat the package's .js files as ES modules. Running npm install adds entries to or for you, usually as caret ranges (a version prefixed with ) that accept compatible updates. The generated pins the exact versions that were installed, so commit it alongside your code.