Skip to content
Tutorials Center
My learning

Topics

TypeScript Reference ยท Modules and Declaration Files

Triple-slash directives

Reference for TypeScript triple-slash directives: reference path, types and lib, placement rules, no-default-lib, and why imports and tsconfig replace most uses.

A triple-slash directive is a single-line comment that starts with three slashes and contains an XML-like tag, such as /// <reference types="node" />. The compiler reads it as an instruction. To JavaScript it is an ordinary comment and does nothing at run time.

The directives mostly pull extra declarations into a file: reference path includes another file, reference types includes the typings of a package, and reference lib includes a built-in library such as dom. They were the main way to connect files before modules, and today they appear mainly in .d.ts files and in tools' generated files (for example, framework setup files like next-env.d.ts).

TypeScript
/// <reference types="node" />
/// <reference lib="es2023" />
/// <reference path="./globals.d.ts" />

Try it

TypeScript A lib directive at the top of the file

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or readFileSync(0)), it gets the next line from this box.

TypeScript A directive after code is only a comment (fails on purpose)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or readFileSync(0)), it gets the next line from this box.

Syntax

TypeScript
/// <reference path="./file.d.ts" />
/// <reference types="package-name" />
/// <reference types="package-name" resolution-mode="import" />
/// <reference lib="es2022" />
/// <reference no-default-lib="true" />
/// <amd-module name="MyName" />
Directive Description
path Adds a file by relative path to the compilation, and orders output when emitting a single file. Resolution is relative to the current file.
types Includes a package's declarations, as if import "pkg" were written, but only for types. Looks in node_modules/@types and in the package itself.
lib Includes one built-in library file by name (dom, es2023, webworker). Same names as the lib option.
no-default-lib Marks a file as a default library; only used by the standard library files themselves.
resolution-mode With types, selects import or require resolution for ES versus CommonJS.

Errors and edge cases:

  • A directive is only recognized in the leading comments of a file, before any statement or declaration. Later ones are plain comments, which is why the second example stops with main.ts(5,28): error TS2584: Cannot find name 'document' instead of working.
  • Only blank lines and other comments may come before it. A directive inside a block comment is ignored.
  • A path or package that cannot be found is error TS6053 ("File not found") or TS2688 ("Cannot find type definition file").
  • Directives pull in types only; they never make the runtime global exist, as the first example shows.

Usage notes

  • Prefer import for modules and tsconfig lib and types for global libraries. A directive in one file affects the whole compilation, which can surprise other files.
  • Do not use reference path between normal modules; the import statement is both clearer and checked.
  • /// <reference types="node" /> at the top of a .d.ts is a polite way for a package to say "my types need Node's types". In app code, install @types/node and list it in types instead.
  • A bundled .d.ts that uses lib="dom" forces DOM types on every project that imports it, even Node-only ones. Library authors avoid this.
  • Generated declaration files keep the directives that your source needs, so check they point at something consumers have.
  • Many /// <reference path> lines with outFile were the old way to order scripts; modules removed that need.