Skip to content

Stop documenting the extinct prepend option for project references #3239

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
jakebailey merged 1 commit into from
Oct 1, 2024
Merged

Stop documenting the extinct prepend option for project references #3239

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
29 changes: 0 additions & 29 deletions packages/documentation/copy/en/project-config/Project References.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -92,34 +92,6 @@ Enabling the [`composite`](/tsconfig#composite) flag changes a few things:
We've also added support for [declaration source maps](https://github.com/Microsoft/TypeScript/issues/14479).
If you enable [`declarationMap`](/tsconfig#declarationMap), you'll be able to use editor features like "Go to Definition" and Rename to transparently navigate and edit code across project boundaries in supported editors.

## `prepend` with `outFile`

You can also enable prepending the output of a dependency using the `prepend` option in a reference:

```js
"references": [
{ "path": "../utils", "prepend": true }
]
```

Prepending a project will include the project's output above the output of the current project.
All output files (`.js`, `.d.ts`, `.js.map`, `.d.ts.map`) will be emitted correctly.

`tsc` will only ever use existing files on disk to do this process, so it's possible to create a project where a correct output file can't be generated because some project's output would be present more than once in the resulting file.
For example:

```txt
A
^ ^
/ \
B C
^ ^
\ /
D
```

It's important in this situation to not prepend at each reference, because you'll end up with two copies of `A` in the output of `D` - this can lead to unexpected results.

## Caveats for Project References

Project references have a few trade-offs you should be aware of.
Expand Down Expand Up @@ -211,7 +183,6 @@ You will need to either set the [`outDir`](/tsconfig#outDir) to an explicit subf
### Structuring for outFiles

Layout for compilations using [`outFile`](/tsconfig#outFile) is more flexible because relative paths don't matter as much.
One thing to keep in mind is that you'll generally want to not use `prepend` until the "last" project - this will improve build times and reduce the amount of I/O needed in any given build.
The TypeScript repo itself is a good reference here - we have some "library" projects and some "endpoint" projects; "endpoint" projects are kept as small as possible and pull in only the libraries they need.

<!--
Expand Down