microsoft / microsoft/TypeScript-Website

Clarify performance impact of project references on ts-server, and recommended usage of 'disableSourceOfProjectReferenceRedirect' or alternatives

Open
#3,332 0 comments 5 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
TypeScript
Stars
2.6k
Forks
1.5k
Avg merge
2d 2h
Merged PRs (30d)
7

Description

From the docs (https://www.typescriptlang.org/tsconfig/#disableSourceOfProjectReferenceRedirect, https://www.typescriptlang.org/docs/handbook/project-references.html), it's clear that:

  • project references enable tsc -b for improved type-checking performance
  • they can also improve tsserver (and therefore IDE) performance if declaration files are 'pre-emitted' and you enable disableSourceOfProjectReferenceRedirect

In a monorepo, where most change units touch multiple projects, you want the behaviour of disableSourceOfProjectReferenceRedirect: false, ie you don't want to have to manually re-generate declaration files if you're changing a leaf project. Here's what's unclear: how is tsserver (and therefore IDE) performance affected by project references in this case? The docs should clarify:

  • whether tsserver performance is expected to improve with project references and disableSourceOfProjectReferenceRedirect: false, compared to without project references?
  • if not, whether there is a recommended setup to let tsserver benefit from project references without having to manually regenerate declaration files?

See also https://stackoverflow.com/questions/67093879/are-typescript-project-references-helpful-with-noemit (no real answer) and https://github.com/microsoft/TypeScript/issues/42607 (where according to the last benchmark by the submitter, project references actually slightly worsen performance, even after the patch).

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with the linked tsconfig reference for disableSourceOfProjectReferenceRedirect and the project references handbook page, then review issues 42607 and the linked Stack Overflow question. Clarify tsserver performance with project references when source redirects remain enabled, and document any recommended setup or limitations for monorepos without manual declaration regeneration.

Written by the indexing model from the issue text.

Assessment

Tech stack
typescript
Domain
documentation
Issue type
Documentation
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.