Capítulo 27 de 36
Triple-slash directives (/// <tag ... />) are single-line XML-in-a-comment compiler instructions valid only at the very top of a file (before any real statement) — mostly legacy today, but still relevant for declaration-file authoring and a few specific build scenarios.
preserve="true"./// <reference path="..." />: declares a file dependency — tells the compiler to include another file in the compilation and (when using outFile) influences output ordering. The compiler preprocesses all root files (from the CLI or tsconfig.json's files list), resolving reference directives depth-first in file order; a relative path resolves relative to the containing file. Referencing a nonexistent file, or a file referencing itself, is a compile error. noResolve disables all of this — reference directives are ignored entirely./// <reference types="..." />: declares a dependency on an @types package (resolved the same way an import specifier resolves a module name) — effectively "import this ambient types package." In a .ts file, prefer the types compiler option/tsconfig field over this directive for the same purpose; the directive form is mainly for .d.ts files./// <reference lib="..." />: explicitly pulls in a built-in lib file (same names as the lib compiler option, e.g. lib="es2017.string", not the full lib.es2017.string.d.ts filename) — the recommended way for declaration-file authors to depend on built-in runtime types (DOM, Symbol, Iterable, etc.) without hand-duplicating forward declarations./// <reference no-default-lib="true"/>: marks a file as itself a default library, telling the compiler not to auto-include the normal lib.d.ts (equivalent to noLib) — this is the directive found at the top of TypeScript's own lib.d.ts variants. Combined with skipDefaultLibCheck, only files carrying this directive get skipped from checking./// <amd-module name="..." />: AMD modules are anonymous by default, which can trip up bundlers processing the output; this directive assigns an explicit name to the generated AMD define(...) call./// <amd-dependency path="..." name="..." />: deprecated — injects a non-TS module dependency into the generated AMD require call; use a normal import "moduleName"; statement instead in new code.preserve="true": without it, reference-type directives (path/types/lib) are stripped from compiled output; adding it keeps them in the emitted file./// <reference lib="es2017.string" />
"foo".padStart(4);
String.prototype.padStart) via a lib reference directive, without changing the project-wide lib compiler option.| Directive | Purpose | Status |
|---|---|---|
<reference path="..."> | include another source file, influence outFile order | active, mostly legacy-project use |
<reference types="..."> | declare a dependency on an @types package | active — prefer tsconfig types field in .ts files |
<reference lib="..."> | pull in a specific built-in lib file | active, common in hand-written .d.ts |
<reference no-default-lib="true"> | opt this file out of the default lib.d.ts | active, mainly for authoring custom lib files |
<amd-module name="..."> | name an anonymous AMD module | active, AMD-specific |
<amd-dependency path="..." /> | inject a non-TS AMD dependency | deprecated — use import "x" |
/// <reference lib="..."> (not hand-duplicated forward declarations) when a hand-written .d.ts needs a specific built-in runtime type.<amd-dependency> in new code — a plain import "moduleName"; statement replaces it.preserve="true" — it's stripped by default..d.ts authoring is the main modern use case for path/lib/no-default-lib directives.import statements are the modern replacement for amd-dependency and, in application code, largely for reference path too.