Typescript project references article #29698
Conversation
|
The latest updates on your projects. Learn more about Vercel for Git ↗︎
|
|
View your CI Pipeline Execution ↗ for commit 30fd263.
☁️ Nx Cloud last updated this comment at |
| @@ -0,0 +1,177 @@ | |||
| --- | |||
| title: What Are TypeScript Project References? | |||
There was a problem hiding this comment.
I wonder if a title like "A Beginner's Guide to TypeScript Project References" or "Everything You Need to Know About TypeScript Project References".
Something that has a bit more SEO juice
| cover_image: /blog/images/2025-01-21/ts-islands.png | ||
| --- | ||
|
|
||
| ## Connecting Projects At The TypeScript Level |
There was a problem hiding this comment.
I think we can cut this paragraph title, feels redundant
| As a practical/pragmatic developer - the TLDR of all of this information is project references allow for more performant builds. | ||
| We've put together [a repo to demonstrate the perfomance gains](https://github.com/jaysoo/typecheck-timings), summarized by this graphic: |
There was a problem hiding this comment.
Let's update the repo link to https://github.com/nrwl/typecheck-timings
| For more information, refer to the docs: https://nx.dev/concepts/sync-generators. | ||
| ``` | ||
| So, offload the mental load to your tools, focus on building your solution, and you should have the best of all worlds. |
There was a problem hiding this comment.
Let's throw our social links down at the bottom
| cover_image: /blog/images/2025-01-21/ts-islands.png | ||
| --- | ||
|
|
||
| ## Connecting Projects At The TypeScript Level |
There was a problem hiding this comment.
Having a title right in the beginning always feels off to me as there's already the main article title immediately followed by another one :) I think we can just drop it here and this first paragraphs serve as the intro
There was a problem hiding this comment.
I agree with Juri that the title underneath the graphic feels off. Maybe one intro sentence makes more sense. Like: `Project References is a feature to help scale your TypeScript monorepo. In this post you will learn all about how it works and how it helps with the performance of your workspaces.
| If we try to run our build script on the `is-odd` project, we see that TypeScript is unable to run the `tsc` command because at the TypeScript level, `is-odd` is not aware of the `is-even` module: | ||
|
|
||
| ```shell | ||
| . > cd is-odd |
There was a problem hiding this comment.
Instead of "cd" into the directory which I think is not relevant here, you should be able to pass a "path" property:
https://github.com/nrwl/nx/tree/master/docs#terminal-output
Like:
``` {% command="tsc" path="~/is-odd" %}
index.ts:1:24 - error TS2792: Cannot find module 'is-even'. Did you mean to set the 'moduleResolution' option to 'nodenext', or to add aliases to the 'paths' option?
1 import { isEven } from 'is-even';
~~~~~~~~~
Found 1 error in index.ts:1
```
| By having the individual `tsconfig.json` files `extend` this base config, they will all get these paths, and now our build command will work: | ||
| ```shell |
There was a problem hiding this comment.
I think we can leave this one away
| With this set up, we can now use the `-b` or `--build` option when building `is-odd` - let's run it now with the `--verbose` flag on: | ||
| ```shell |
There was a problem hiding this comment.
use the terminal-output fence for this one instead of shell.
|  | ||
| In addition to the time savings we saw reduced memory usage (~< 1GB vs 3 GB). This makes sense given what we saw about how project references work. This is actually a very good thing for CI pipelines, as exceeding memory usuage is a common issue we see with our clients for their TypeScript builds. Less memory usuage means we can use smaller machines, which saves on the CI costs. |
There was a problem hiding this comment.
| In addition to the time savings we saw reduced memory usage (~< 1GB vs 3 GB). This makes sense given what we saw about how project references work. This is actually a very good thing for CI pipelines, as exceeding memory usuage is a common issue we see with our clients for their TypeScript builds. Less memory usuage means we can use smaller machines, which saves on the CI costs. | |
| In addition to the time savings we saw reduced memory usage (~< 1GB vs 3 GB). This makes sense given what we saw about how project references work. This is actually a very good thing for CI pipelines, as exceeding memory usage is a common issue we see with our clients for their TypeScript builds. Less memory usage means we can use smaller machines, which saves on the CI costs. |
There was a problem hiding this comment.
this one has really low contrast. is there any way to improve it?
There was a problem hiding this comment.
There is this version, with dark mode off
There was a problem hiding this comment.
yeah maybe that's better 🤔. For me it is mostly the text on the side is really small plus also contrast wise not great. So it's hard to read.
| import { isEven } from 'is-even'; | ||
| ``` | ||
| TypeScript needs to be informed as to how to find the module named `is-even`. The error message here actually suggests that we may have forgotten to add aliases to the 'paths' option. To do this we can adjust our `tsconfig.json` file at the root of the monorepo: |
There was a problem hiding this comment.
| TypeScript needs to be informed as to how to find the module named `is-even`. The error message here actually suggests that we may have forgotten to add aliases to the 'paths' option. To do this we can adjust our `tsconfig.json` file at the root of the monorepo: | |
| TypeScript needs to be informed as to how to find the module named `is-even`. The error message here actually suggests that we may have forgotten to add aliases to the `paths` option. To do this we can adjust our `tsconfig.json` file at the root of the monorepo: |
| is-odd | ||
| index.d.ts | ||
| index.js | ||
| index.tx |
There was a problem hiding this comment.
| index.tx | |
| index.ts |
|  | ||
| In addition to the time savings we saw reduced memory usage (~< 1GB vs 3 GB). This makes sense given what we saw about how project references work. This is actually a very good thing for CI pipelines, as exceeding memory usuage is a common issue we see with our clients for their TypeScript builds. Less memory usuage means we can use smaller machines, which saves on the CI costs. |
There was a problem hiding this comment.
I think we should emphasize the "performance" part more and where this comes from. it is kinda mentioned, but maybe we can emphasize it better 🤔. Like the "breaking down TS programs" into smaller units, the incremental nature of it, the fact that there are tsconfig.tsbuildinfo files generated which tsc -b uses to avoid recomputation of types etc, thus being incremental etc :)
| Notice how both `is-even` AND `is-odd` now have a compiled `index.d.ts` declaration file and `index.js`. They also both have a `tsconfig.base.json` file now (this holds the additional data TypeScript needs to determine which builds are needed). With the `--build` option, TypeScript is now operating as a build orchestrator - by finding all referenced projects, determining if they are out-of-date, and then building them in the correct order. | ||
| ## So What Does This Mean For You |
| As a practical/pragmatic developer - the TLDR of all of this information is project references allow for more performant builds. | ||
| We've put together [a repo to demonstrate the perfomance gains](https://github.com/jaysoo/typecheck-timings), summarized by this graphic: |
There was a problem hiding this comment.
| We've put together [a repo to demonstrate the perfomance gains](https://github.com/jaysoo/typecheck-timings), summarized by this graphic: | |
| We've put together [a repo to demonstrate the performance gains](https://github.com/jaysoo/typecheck-timings), summarized by this graphic: |
| As we can see, there's an error associated with this line: | ||
| ```typescript | ||
| import { isEven } from 'is-even'; | ||
| ``` |
There was a problem hiding this comment.
I feel like this should be shown as part of the setup before the paragraph:
If we try to run our build script on the
is-oddproject...
So, we give all the relevant context before building and seeing the error.
| ```json | ||
| { | ||
| "extends": "../tsconfig.base.json", |
There was a problem hiding this comment.
We don't show anywhere that we need to set composite: true.
https://nx-dev-git-fork-zackderose-typescript-project-refer-8c9adb-nrwl.vercel.app/blog/typescript-project-references