Modules, packages & libraries

How TypeScript modules work, how Node and bundlers resolve them, and how to build, type and publish a library in 2026 (TS 5.9 and 6.0, Node 24). For patterns inside a module see Design patterns.

ES module syntax

export const PI = 3.14159;
export type Vec = { x: number; y: number };
 
export function add(a: Vec, b: Vec): Vec {
  return { x: a.x + b.x, y: a.y + b.y };
}
 
export default function length(v: Vec): number {
  return Math.hypot(v.x, v.y);
}

import length, { add, type Vec } from "./math.js";
import * as math from "./math.js";
 
const v: Vec = add({ x: 3, y: 0 }, { x: 0, y: 4 });
length(v) === math.default(v); // true: 5
 
// code-split or conditional loading
if (v.x > 0) {
  const { PI } = await import("./math.js");
  PI.toFixed(2);
}

Imports are live, read-only bindings: an importer sees later changes to an exported let, but cannot assign to it. Module code runs once, in strict mode, and top-level await works in ESM only.

verbatimModuleSyntax

With verbatimModuleSyntax: true (TS 5.0+, default in tsc --init since 5.9) TypeScript emits imports exactly as written, minus anything marked type. That is what single-file tools (esbuild, SWC, Node type stripping) do anyway, so enable it.

It also forbids ESM syntax in files that emit CommonJS; there you must write import x = require("x") and export =. One more reason to ship ESM.

import.meta

import { readFile } from "node:fs/promises";
import { join } from "node:path";
 
const tmpl = await readFile(
  join(import.meta.dirname, "template.html"),
  "utf8",
);
const asset = new URL("./logo.svg", import.meta.url);

Import attributes

import pkg from "./package.json" with { type: "json" };
pkg.version; // typed from the JSON (resolveJsonModule)

• with { type: "json" } is required by Node and browsers for JSON; only a default export. The old assert form is removed (an error under nodenext and in TS 6.0).
• TS 5.3+ parses attributes; module: nodenext checks JSON imports (5.7+).
• JSON modules are Baseline 2025; CSS modules (type: "css") are Chromium-only.
• import defer * as m from "./m.js" (TS 5.9, stage 3) loads now but runs on first use; only with module: preserve or esnext and a runtime/bundler that supports it.

CommonJS interop

In TypeScript, a CommonJS file (.cts, or .ts without "type": "module") written in CJS style:

import os = require("node:os");
 
function greet(name: string): string {
  return `hi ${name} from ${os.hostname()}`;
}
export = greet;

import greet from "./greet.cjs"; // module.exports -> default
import { createRequire } from "node:module";
 
greet("ada");
const require = createRequire(import.meta.url);
const legacy = require("./greet.cjs") as typeof greet;

esModuleInterop and the default-import confusion

Node gives ESM importers module.exports as the default export. Bundlers and esModuleInterop additionally honor the __esModule flag that transpilers set, which is where code that works in a bundler breaks in Node:

• esModuleInterop (implied by module: node* and preserve, always on in TS 6.0) makes import fs from "fs" legal and makes import * as express from "express"; express() an error: a namespace object is never callable.
• module: nodenext models Node exactly, so trust its errors over "it worked in Vite".

require(esm)

Node can require() an ES module synchronously: unflagged in 20.19 and 22.12, stable in 25.4. TypeScript models it under module: nodenext (5.8+) and node20 (5.9+), not node16/node18.

• require() returns the namespace object; the default export is .default.
• export { thing as "module.exports" } makes require() return thing directly.
• Throws ERR_REQUIRE_ASYNC_MODULE if the module graph uses top-level await.
• Detect with process.features.require_module.

This is what makes ESM-only packages usable from CommonJS apps.

Module resolution

module says what the runtime is and what format to emit; moduleResolution follows from it.

File extensions in imports

Under nodenext, relative ESM imports need a full extension. Write the output extension; TypeScript maps it back to the source file:

Or write "./util.ts" and set rewriteRelativeImportExtensions (5.7+, rewrites relative paths on emit) or allowImportingTsExtensions (only with noEmit or declaration-only emit).

Module format detection

Node 22.7+ also sniffs ESM syntax in ambiguous .js files, but TypeScript only reads "type", so always set it.

tsconfig for libraries

{
  "compilerOptions": {
    "target": "es2023",
    "lib": ["es2023"],
    "module": "nodenext",
    "types": ["node"],
    "rootDir": "src",
    "outDir": "dist",
 
    "strict": true,
    "noUncheckedIndexedAccess": true,
    "exactOptionalPropertyTypes": true,
    "noImplicitOverride": true,
 
    "verbatimModuleSyntax": true,
    "isolatedModules": true,
    "isolatedDeclarations": true,
    "erasableSyntaxOnly": true,
    "rewriteRelativeImportExtensions": true,
 
    "declaration": true,
    "declarationMap": true,
    "sourceMap": true,
    "skipLibCheck": true
  },
  "include": ["src"],
  "exclude": ["**/*.test.ts"]
}

// with isolatedDeclarations
// ❌ error TS9007: needs an explicit return type
// export function add(a: number, b: number) {
//   return a + b;
// }
 
export function add(a: number, b: number): number {
  return a + b;
}
export const ZERO: number = 0;

package.json

An ESM-only library:

{
  "name": "@me/geometry",
  "version": "1.2.0",
  "type": "module",
  "exports": {
    ".": {
      "types": "./dist/index.d.ts",
      "default": "./dist/index.js"
    },
    "./shapes/*": {
      "types": "./dist/shapes/*.d.ts",
      "default": "./dist/shapes/*.js"
    },
    "./internal/*": null,
    "./package.json": "./package.json"
  },
  "imports": { "#util/*": "./dist/util/*.js" },
  "files": ["dist", "src"],
  "sideEffects": false,
  "engines": { "node": ">=20.19" },
  "peerDependencies": { "react": "^18.3 || ^19" },
  "peerDependenciesMeta": { "react": { "optional": true } },
  "dependencies": { "zod": "^4.0.0" },
  "devDependencies": { "typescript": "~5.9.3" }
}

What the tarball of the package above contains, and which exports entry reaches each file:

@me/geometry/├── package.json├── README.md├── LICENSE├── dist/│   ├── index.js        # "." default│   ├── index.d.ts      # "." types│   ├── index.d.ts.map  # declarationMap: jump to src/│   ├── shapes/│   │   ├── circle.js   # @me/geometry/shapes/circle│   │   └── circle.d.ts│   └── util/│       └── math.js     # "#util/math", package-private└── src/                # shipped only for declaration maps    ├── index.ts    └── shapes/        └── circle.ts

Dual package (only if you must support old CJS consumers):

{
  "exports": {
    ".": {
      "import": {
        "types": "./dist/index.d.mts",
        "default": "./dist/index.mjs"
      },
      "require": {
        "types": "./dist/index.d.cts",
        "default": "./dist/index.cjs"
      }
    }
  }
}

dist/├── index.mjs    # "import" default├── index.d.mts  # "import" types├── index.cjs    # "require" default└── index.d.cts  # "require" types

Each format needs its own declaration file: a single .d.ts for both makes one side "masquerade" as the wrong format (attw flags this).

Dependency kinds

Types leak: if your published .d.ts imports from @types/node or another package, that package must be a dependency or peer, not a devDependency.

Building

# tsc only
tsc -p tsconfig.build.json
 
# tsdown: ESM + declarations into dist/
npx tsdown src/index.ts --format esm --dts

import { defineConfig } from "tsdown";
 
export default defineConfig({
  entry: ["src/index.ts", "src/shapes/*.ts"],
  format: ["esm"],
  dts: true,
  sourcemap: true,
  publint: true,
});

• No bundler (tsc): output mirrors source, perfect tree shaking, readable stack traces, consumers' bundlers do the rest. Relative imports need .js extensions (or .ts plus rewriting).
• Bundler: needed to inline internal deps, emit two formats, or handle CSS/JSX assets. Keep external everything in dependencies/peerDependencies.

Declaration files & augmentation

A .d.ts file holds types only: declare statements and exported types, no values.

// an untyped dependency
declare module "legacy-lib" {
  export function parse(input: string): number;
  export const version: string;
}
 
// asset imports handled by a bundler
declare module "*.svg" {
  const url: string;
  export default url;
}

Global augmentation must live in a module (a file with an import or export):

declare global {
  interface Window {
    __APP_VERSION__: string;
  }
  // `var` (not let/const) adds to globalThis
  var __DEV__: boolean;
}
export {};

Module augmentation merges into a package's interfaces. Import something (or export {}) so the file is a module; otherwise declare module replaces the package instead:

import "react";
 
declare module "react" {
  interface CSSProperties {
    [key: `--${string}`]: string | number; // CSS variables
  }
}

• You can add members to interfaces and namespaces, not new top-level exports or overrides of existing member types.
• /// <reference types="vite/client" /> pulls in a types package; prefer "types" in tsconfig. /// <reference path="..." /> and /// <reference lib="..." /> are rarely needed outside hand-written .d.ts bundles.
• Contributing types for someone else's package goes to DefinitelyTyped (@types/pkg).

Publishing checklist

npm run build && npm test
npm pack --dry-run      # what exactly ships
npx publint             # lint package.json + exports
npx @arethetypeswrong/cli --pack .  # types per mode
npx @arethetypeswrong/cli --pack . --profile esm-only
npm publish --access public  # 1st publish, @scope

1. exports covers every public entry; types first, default last.
2. files ships dist (and src if you ship declaration maps); no tests, no secrets.
3. .d.ts output checked by attw; --profile esm-only ignores CJS failures by design.
4. engines, peerDependencies ranges and sideEffects are accurate.
5. Version bumped per semver; changelog written.
6. Publish from CI with trusted publishing (OIDC, npm 11.5.1+, Node 22.14+): no stored token, and provenance attestations are added automatically for public repos.

Changesets keeps versions and changelogs in step, especially in monorepos:

npx @changesets/cli init   # creates .changeset/
npx changeset              # describe a change + bump type
npx changeset version      # apply bumps, write CHANGELOG.md
npx changeset publish      # publish changed packages, tag

JSR (jsr.io) publishes TypeScript source directly and generates docs; it works with npm, pnpm, Bun, Deno. It rejects "slow types" (exports without explicit types), the same rule as isolatedDeclarations.

{
  "name": "@me/geometry",
  "version": "1.2.0",
  "exports": "./src/index.ts"
}

npx jsr publish          # or: deno publish
npx jsr add @me/geometry # consumers

Monorepos & project references

workspace:* is rewritten to the real version on publish. Turborepo or Nx add task caching on top.

Project references split one big type-check into packages that build in dependency order and cache their results:

repo/├── package.json           # "workspaces": ["packages/*"]├── tsconfig.base.json     # shared compilerOptions├── tsconfig.json          # "files": [], refs both packages└── packages/    ├── ui/    │   ├── package.json   # "name": "@me/ui"    │   ├── tsconfig.json  # composite: true    │   ├── tsconfig.tsbuildinfo    │   ├── src/    │   │   └── index.ts    │   └── dist/          # .js + .d.ts, read by app    └── app/        ├── package.json   # "@me/ui": "workspace:*"        ├── tsconfig.json  # references ../ui        ├── tsconfig.tsbuildinfo        ├── src/        │   └── main.ts        └── dist/

{
  "extends": "../../tsconfig.base.json",
  "compilerOptions": {
    "composite": true,
    "rootDir": "src",
    "outDir": "dist"
  },
  "include": ["src"],
  "references": [{ "path": "../ui" }]
}

{
  "files": [],
  "references": [
    { "path": "packages/ui" },
    { "path": "packages/app" }
  ]
}

Lighter alternative: "internal packages" whose exports point at .ts source under a custom condition ("@me/source": "./src/index.ts") plus customConditions: ["@me/source"] in tsconfig, so editors see live types without a build step.

Running TS directly

Node's type stripping replaces types with whitespace and runs the result. Its limits:

• No enum, runtime namespace, parameter properties, import x = require(), or decorators (--experimental-transform-types covered some of these; removed in Node 26).
• Relative imports need the real .ts extension; tsconfig.json is ignored, so no paths (use package.json "imports" with # instead).
• Type-only imports must say import type (hence verbatimModuleSyntax).
• No .tsx, and nothing inside node_modules is stripped: publish JavaScript.

node src/main.ts          # Node 22.18+ / 24
node --watch src/main.ts
bun src/main.ts
npx tsx watch src/main.ts
npx tsc --noEmit          # the type check none of them do

Erasable replacements for the banned constructs:

// enum Dir { Up, Down }  ->  object + union type
const Dir = { Up: "up", Down: "down" } as const;
type Dir = (typeof Dir)[keyof typeof Dir]; // "up" | "down"
 
// constructor(private x: number) {}  ->  explicit field
class Point {
  #x: number;
  constructor(x: number) {
    this.#x = x;
  }
  get x(): number {
    return this.#x;
  }
}
 
const move = (d: Dir, p: Point): string => `${d} ${p.x}`;
move(Dir.Up, new Point(1));

References

• MDN: JavaScript modules (opens in a new tab), import attributes (opens in a new tab), import.meta (opens in a new tab)
• TypeScript: Modules reference (opens in a new tab), Choosing compiler options (opens in a new tab), Project references (opens in a new tab), Declaration merging (opens in a new tab)
• TypeScript release notes 5.7 (opens in a new tab), 5.8 (opens in a new tab), 5.9 (opens in a new tab), 6.0 (opens in a new tab)
• Node.js: Packages (opens in a new tab), ESM (opens in a new tab), require(esm) (opens in a new tab), TypeScript (opens in a new tab)
• publint (opens in a new tab), Are the types wrong? (opens in a new tab), tsdown (opens in a new tab), Changesets (opens in a new tab), npm trusted publishing (opens in a new tab), JSR (opens in a new tab)