Configure TypeScript Project References in an Nx Workspace

In Nx 20, the @nx/js plugin provides the ability to incrementally build projects in a monorepo using TypeScript Project References. Nx also provides a ts preset for create-nx-workspace that configures project references and uses workspaces to link projects instead of TypeScript compilerOptions Paths.

The TypeScript team recommends using project references when working in a monorepo, but until now the configuration settings were difficult to maintain. Each project is required to list its own project dependencies in the references property of the tsconfig.json file so that TypeScript can incrementally compile projects in the correct order. In a large monorepo, maintaining those settings manually is cost prohibitive. To solve this problem, the @nx/js plugin registers a sync generator to automatically update the references based on Nx's project graph before any TypeScript build task is executed.

Create a New Nx Workspace Using Project References

We anticipate that this style of compiling projects will eventually become the default, but currently it will only be enabled for repositories configured in a specific way. Existing workspaces will continue to function as usual and there is no migration path yet. You can generate a new repository with these settings by using the --preset=ts flag of the create-nx-workspace command.

This will generate an empty repository that is configured to use TypeScript project references. To see the new functionality in action, create some TypeScript projects and make sure to use the tsc bundler option.

These generators will detect that your repository is configured to use project references and update the configuration accordingly. If these generators were executed in an Nx repository that used compilerOptions.paths, they would update that setting instead.

To make cart depend on utils, update packages/cart/package.json like this:

Now if you run nx build cart or directly run nx sync, the packages/cart/tsconfig.json file will have its references updated for you.

Project Reference Configuration Files

Nx expects the following configuration settings to be in place in order to use TypeScript project references to build projects. Most of this configuration is set up and maintained for you automatically by Nx.

Identify projects in the workspaces property in the root package.json file.

The root tsconfig.base.json should contain a compilerOptions property and no other properties. compilerOptions.composite and compilerOptions.declaration should be set to true. compilerOptions.paths should not be set.

The root tsconfig.json file should extend tsconfig.base.json and not include any files. It needs to have references for every project in the repository so that editor tooling works correctly.

Each project's tsconfig.json file should extend the tsconfig.base.json file and list references to the project's dependencies.

Each project's tsconfig.lib.json file extends the project's tsconfig.json file and adds references to the tsconfig.lib.json files of project dependencies.

The project's tsconfig.spec.json does not need to reference project dependencies.