Project References by RyanCavanaugh · Pull Request #788 · microsoft/TypeScript-Handbook (original) (raw)
This repository was archived by the owner on Oct 12, 2022. It is now read-only.
Conversation8 Commits1 Checks0 Files changed
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.Learn more about bidirectional Unicode characters
[ Show hidden characters]({{ revealButtonHref }})
Adds documentation for project references and tsc -b
I thought we are calling them "Composite Projects", hence the composite tsconfig property name.
| assert.areEqual(converter.celsiusToFahrenheit(0), 32); |
|---|
| ``` |
| Previously, this structure was rather awkward to work with if you used a single tsconfig file: |
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
since this is a handbook page, and not a release blog, i would not use "previously". i would just say "Building as a single project would"
| When loading types from a referenced project, types always come from the generated `.d.ts` file instead of an implementation (`.ts`) file. This is much faster because all type inference has already taken place, there's no need to check for errors in statements or expressions, and the amount of memory and disk I/O needed is also lower. However, this means that the referenced project does need to be built before the referencing project can understand its own types. If you open a multi-project solution in an editor, you may see a large number of errors caused by this until the referenced projects get built. We're working on a behind-the-scenes .d.ts generation process that should be able to mitigate this, but for now we recommend informing developers that they should build after cloning. |
| Because `.d.ts` files themselves don't *generate* new `.d.ts` files, you'll want to write any hand-authored types in a `.ts` file instead of a `.d.ts` file, even if you don't intend to include any executable statements in the file. |
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
i do not think this is what we want ppl to be doing.. they just need to make the .d.ts files in a shared location. and include them in both projects.
| * All implementation files must be matched by an `include` pattern or listed in the `files` array. If this constraint is violated, `tsc` will inform you which files weren't specified. |
|---|
| * `declaration` defaults to `true` |
| These changes won't affect many projects in a substantial way. We recommend turning on `composite` in most projects, even if they're not using project references yet. |
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
should we add it to tsc --init?
| # More Options for Project References |
| ## `declarationMaps` |
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
i think we should make this on by default if composite is set. this way ppl do not have to worry about it.
| # Build Mode for TypeScript |
| A long-awaited feature is smart incremental builds for TypeScript projects. In 3.0 you can use the `--build` flag with `tsc`. This is effectively a new entry point for `tsc` that behaves more like a build orchestrator than a simple compiler. `--build` changes the meaning of other flags, so it must be the first argument to `tsc` if it's being used. |
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
do not think you need the long-awaited part, it will not make much sense when someone looks at the handbook a year from now.
| ## Caveats |
| Normally, `tsc` will produce outputs (`.js` and `.d.ts`) in the presence of syntax or type errors, unless `noEmitOnError` is on. Doing this in an incremental build system would be very bad - if one of your out-of-date dependencies had a new error, you'd only see it *once* because a subsequent build would skip building the now up-to-date project. For this reason, `tsc -b` effectively acts as if `noEmitOnError` is enabled for all all projects. |
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
i would just say if one project has any errors, the compiler will not attempt building referencing projects. (people do not need to know what the noEmitOnError behavior is to understand that part). you can always have a reference to it at the end.
| Using project references with monorepo management tools like `lerna` is straightforward - simply add references according to the dependencies of your code. This should generally mirror the dependencies listed in your `package.json`s. Lerna's symlinking will do the rest! |
| You can see the example repo https://github.com/RyanCavanaugh/learn-a for a cloneable example with a walkthrough file showing how to accomplish various tasks. |
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
We should have this in the handbook or on the TypeScriptSamples repo.
2 participants
