As of TypeScript 5.5, the compiler does not generate reference directives, and doesnot emit handwritten triple-slash directives to output files unless those directives are marked aspreserve="true".

/// <reference path="..." />

The/// <reference path="..." /> directive is the most common of this group.It serves as a declaration ofdependency between files.

Triple-slash references instruct the compiler to include additional files in the compilation process.

They also serve as a method to order the output when usingout oroutFile.Files are emitted to the output file location in the same order as the input after preprocessing pass.

Preprocessing input files

The compiler performs a preprocessing pass on input files to resolve all triple-slash reference directives.During this process, additional files are added to the compilation.

The process starts with a set ofroot files;these are the file names specified on the command-line or in thefiles list in thetsconfig.json file.These root files are preprocessed in the same order they are specified.Before a file is added to the list, all triple-slash references in it are processed, and their targets included.Triple-slash references are resolved in a depth-first manner, in the order they have been seen in the file.

A triple-slash reference path is resolved relative to the containing file, if a relative path is used.

Errors

It is an error to reference a file that does not exist.It is an error for a file to have a triple-slash reference to itself.

Using--noResolve

If the compiler flagnoResolve is specified, triple-slash references are ignored; they neither result in adding new files, nor change the order of the files provided.

/// <reference types="..." />

Similar to a/// <reference path="..." /> directive, which serves as a declaration ofdependency, a/// <reference types="..." /> directive declares a dependency on a package.

The process of resolving these package names is similar to the process of resolving module names in animport statement.An easy way to think of triple-slash-reference-types directives are as animport for declaration packages.

For example, including/// <reference types="node" /> in a declaration file declares that this file uses names declared in@types/node/index.d.ts;and thus, this package needs to be included in the compilation along with the declaration file.

For declaring a dependency on an@types package in a.ts file, usetypes on the command line or in yourtsconfig.json instead.Seeusing@types,typeRoots andtypes intsconfig.json files for more details.

/// <reference lib="..." />

This directive allows a file to explicitly include an existing built-inlib file.

Built-inlib files are referenced in the same fashion as thelib compiler option intsconfig.json (e.g. uselib="es2015" and notlib="lib.es2015.d.ts", etc.).

For declaration file authors who rely on built-in types, e.g. DOM APIs or built-in JS run-time constructors likeSymbol orIterable, triple-slash-reference lib directives are recommended. Previously these .d.ts files had to add forward/duplicate declarations of such types.

For example, adding/// <reference lib="es2017.string" /> to one of the files in a compilation is equivalent to compiling with--lib es2017.string.

ts
///<referencelib="es2017.string"/>
"foo".padStart(4);

/// <reference no-default-lib="true"/>

This directive marks a file as adefault library.You will see this comment at the top oflib.d.ts and its different variants.

This directive instructs the compiler tonot include the default library (i.e.lib.d.ts) in the compilation.The impact here is similar to passingnoLib on the command line.

Also note that when passingskipDefaultLibCheck, the compiler will only skip checking files with/// <reference no-default-lib="true"/>.

/// <amd-module />

By default AMD modules are generated anonymous.This can lead to problems when other tools are used to process the resulting modules, such as bundlers (e.g.r.js).

Theamd-module directive allows passing an optional module name to the compiler:

amdModule.ts

ts
///<amd-modulename="NamedModule"/>
exportclassC {}

Will result in assigning the nameNamedModule to the module as part of calling the AMDdefine:

amdModule.js

js
define("NamedModule", ["require","exports"],function (require,exports) {
varC = (function () {
functionC() {}
returnC;
  })();
exports.C =C;
});

/// <amd-dependency />

Note: this directive has been deprecated. Useimport "moduleName"; statements instead.

/// <amd-dependency path="x" /> informs the compiler about a non-TS module dependency that needs to be injected in the resulting module’s require call.

Theamd-dependency directive can also have an optionalname property; this allows passing an optional name for an amd-dependency:

ts
///<amd-dependencypath="legacy/moduleA"name="moduleA"/>
declarevarmoduleA:MyType;
moduleA.callStuff();

Generated JS code:

js
define(["require","exports","legacy/moduleA"],function (
require,
exports,
moduleA
) {
moduleA.callStuff();
});

preserve="true"

Triple-slash directives can be marked withpreserve="true" to prevent the compiler from removing them from the output.

For example, these will be erased in the output:

ts
///<referencepath="..."/>
///<referencetypes="..."/>
///<referencelib="..."/>

But these will be preserved:

ts
/// <reference path="..." preserve="true" />
/// <reference types="..." preserve="true" />
/// <reference lib="..." preserve="true" />