Skip to content

Commit 9ef7804

Browse files
Update triple-slash directive docs for preserve=true (#3265)
Co-authored-by: Daniel Rosenwasser <DanielRosenwasser@users.noreply.github.com>
1 parent 958f531 commit 9ef7804

File tree

1 file changed

+23
-5
lines changed

1 file changed

+23
-5
lines changed

packages/documentation/copy/en/reference/Triple-Slash Directives.md

Lines changed: 23 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,8 @@ Triple-slash directives are **only** valid at the top of their containing file.
1313
A triple-slash directive can only be preceded by single or multi-line comments, including other triple-slash directives.
1414
If they are encountered following a statement or a declaration they are treated as regular single-line comments, and hold no special meaning.
1515

16+
As of TypeScript 5.5, the compiler does not generate reference directives, and does _not_ emit handwritten triple-slash directives to output files unless those directives are marked as [`preserve="true"`](#preservetrue).
17+
1618
## `/// <reference path="..." />`
1719

1820
The `/// <reference path="..." />` directive is the most common of this group.
@@ -55,11 +57,6 @@ An easy way to think of triple-slash-reference-types directives are as an `impor
5557
For example, including `/// <reference types="node" />` in a declaration file declares that this file uses names declared in `@types/node/index.d.ts`;
5658
and thus, this package needs to be included in the compilation along with the declaration file.
5759

58-
Use these directives only when you're authoring a `d.ts` file by hand.
59-
60-
For declaration files generated during compilation, the compiler will automatically add `/// <reference types="..." />` for you;
61-
A `/// <reference types="..." />` in a generated declaration file is added _if and only if_ the resulting file uses any declarations from the referenced package.
62-
6360
For declaring a dependency on an `@types` package in a `.ts` file, use [`types`](/tsconfig#types) on the command line or in your `tsconfig.json` instead.
6461
See [using `@types`, `typeRoots` and `types` in `tsconfig.json` files](/docs/handbook/tsconfig-json.html#types-typeroots-and-types) for more details.
6562

@@ -142,3 +139,24 @@ define(["require", "exports", "legacy/moduleA"], function (
142139
moduleA.callStuff();
143140
});
144141
```
142+
143+
144+
## `preserve="true"`
145+
146+
Triple-slash directives can be marked with `preserve="true"` to prevent the compiler from removing them from the output.
147+
148+
For example, these will be erased in the output:
149+
150+
```ts
151+
/// <reference path="..." />
152+
/// <reference types="..." />
153+
/// <reference lib="..." />
154+
```
155+
156+
But these will be preserved:
157+
158+
```ts
159+
/// <reference path="..." preserve="true" />
160+
/// <reference types="..." preserve="true" />
161+
/// <reference lib="..." preserve="true" />
162+
```

0 commit comments

Comments
 (0)