tsc --build / Project References Feedback & Discussion

[RyanCavanaugh]

Continuation of #3469 "Medium-sized Projects" which has grown too large for GitHub to display comfortably

Please use this thread for feedback, general discussion, questions, or requests for help / "is this a bug" discussions.

Active bugs / PRs in this area:

• Project References TypeScript-Handbook#788 Handbook page

Possible next steps:

• (none yet; @Andy-MS) Find unloaded downstream projects during rename
• Infer project references from common monorepo patterns / tools #25376 Infer project references from monorepo tooling package.json files
• Terse mode output from tsc --build #25562 Terse mode output for tsc -b
• (none yet; @weswigham ?) Intermediate build outputs to temp folders
• (none; stretch) Parallelization / worker processes under tsc -b

Other interesting links:

• https://github.com/RyanCavanaugh/learn-a - sample project references repo using lerna
• https://github.com/RyanCavanaugh/project-references-outfile - sample project references repo using --outFile
• Support "medium-sized" projects #3469 (comment) Ryan's outline of what we're doing/did and why
• Support "medium-sized" projects #3469 (comment) pre-draft of handbook page
• https://github.com/RyanCavanaugh/learn-a/pull/3/files learn-a repo using yarn workspaces!

[timfish]

A couple of things:

1. watch doesn't currently output an initial build. It waits until the first file change. This differs to non build mode.
2. How is build order determined? I found I had to order the project references in dependency order to get the build to complete first time without error

[RyanCavanaugh]

@timfish thanks! Re 1 - PR up at #25610. For the other issue, can you sketch out the files you have? The order is supposed to be a simple topological sort that should always yield a correct ordering. I'll try to repro locally in the meantime based on what you've described

Edit: Not sure how to repro - I changed the TypeScript repo's src/tsconfig.json to be in effectively random order and it still figured out a valid build order. Will need details on this.

[EisenbergEffect]

@RyanCavanaugh Were you all able to land the cross-project rename for the RC?

[RyanCavanaugh]

@EisenbergEffect we have "upstream" renames (renaming a usage in client affects declarations in shared) but not "downstream" (renames in shared affecting uses in server and client) yet

[EisenbergEffect]

Gotcha. Any ideas is you'll be able to get the downstream rename in for the final release? or have you already determined that it needs to push out to 3.1 or beyond?

[RyanCavanaugh]

It looks like we can probably get downstream renames for loaded projects in by 3.0 final. Detecting which other projects on your computer need to be loaded to do an "exhaustive downstream rename" is looking dicey - we haven't found any mechanisms that would let us short-circuit that work when the symbol being renamed is exported from the current file.

[newtack]

I am using the API to build Typescript projects, including createWatchProgram and createWatchCompilerHost.

1. Are these updated to use the new project references and 2) do I need to do anything else in my code other than update the tsconfig.json?

[RyanCavanaugh]

If you're hosting the compiler API, you don't need to do anything new for project references; everything should work as-is. If you want to take advantage of the new --build mode features, the entry point is createSolutionBuilder and you'll need to provide a BuildHost and CompilerHost along with the file timestamp APIs on the latter.

To migrate to using project references in your code itself, updating your tsconfig.json to a) add references and b) add composite: true may be sufficient - if not, you'll see errors informing you what else needs to happen. Writing a comprehensive migration guide has been a difficult task because project setups are so varied - I'm hoping we can find migrations from early adopters as something to point people to, but it's hard to give guidance without seeing specific build layouts.

[newtack]

Thanks @RyanCavanaugh

Are there any examples for "createSolutionBuilder" and "timestamp API"?

[timfish]

@RyanCavanaugh ref: Build order.

I'll try to get a repo reproducing this although it won't be until next week.

If I'm just adding all references to a root tsconfig, it should work out the dependency tree from that?