Feature request: Report an error for missing or unused project references

🔍 Search Terms

composite project missing unused project reference

✅ Viability Checklist

My suggestion meets these guidelines:

• This wouldn't be a breaking change in existing TypeScript/JavaScript code
• This wouldn't change the runtime behavior of existing JavaScript code
• This could be implemented without emitting different JS based on the types of the expressions
• This isn't a runtime feature (e.g. library functionality, non-ECMAScript syntax with JavaScript output, new syntax sugar for JS, etc.)
• This feature would agree with the rest of TypeScript's Design Goals.

⭐ Suggestion

Please add compiler options that would report an error if:

• A module is imported from another package in the composite project without a corresponding project reference in tsconfig.json.
• A project reference exists in tsconfig.json that doesn't correspond to any imported module.

📃 Motivating Example

I work on a very large monorepo-based project that uses a TypeScript composite project. I'll explain the setup in detail just to make sure I don't leave anything out that might be helpful. The file system layout looks similar to this:

package.json
packages/
├── tsconfig.json
├── foo/
│   ├── package.json
│   ├── tsconfig.json
│   ├── src/
│   └── dist/
├── bar/
│   ├── package.json
│   ├── tsconfig.json
│   ├── src/
│   └── dist/
├── ...

We "install" all of these packages in the root package.json using, for example:

npm install packages/foo

This symlinks them into node_modules so that they can be imported by other packages. The name of each package is @company/PACKAGE, so that packages/foo is symlinked to node_modules/@company/foo.

Using this setup, we can build all packages using tsc --build packages. The root tsconfig.json uses a solution-style configuration and just references all of the individual packages.

For tsc to understand the dependencies between these packages, so that they can be built in the right order, we naturally need to specify project references in each package's tsconfig.json. For example, if bar contains a source file that includes this import statement:

import { value } from '@company/foo';

...then bar needs to contain a corresponding project reference for foo in tsconfig.json:

{
  // ...
  "references": [
    { "path": "../foo" },
  }
}

That's the setup. The actual problem is simply this: there is no way to ask the compiler to report an error if one of these project references is missing or unused. Without this feature, this entire setup is a gigantic footgun:

• If a project reference that should be there is missing, the packages may be built in the wrong order, or dependencies may not be rebuilt when they should be. This may cause the build to fail, or cause types to be checked against a previous version of the code, or may just work by coincidence until someone tries to make a seemingly-unrelated change and breaks the build.
• If a project reference that is no longer necessary is not removed, it may cause false dependencies to be rebuilt unnecessarily often, slowing down incremental builds.

To avoid this, we've implemented a tool that parses the output of --traceResolution and compares it to the content of each package's tsconfig.json to detect such cases and cause a CI job to fail. (Today, we might implement it on top of --explainFiles instead.) This tool is very slow, because to get complete output from --traceResolution, it needs to rebuild everything. It's also based on an unstable interface - parsing compiler log output - that might break at any time.

It would be incredibly helpful if there were compiler options that would do this job for us as part of the normal process of compilation. The really critical thing is to detect missing project references, since they're necessary for correctness, but being able to detect unused ones would be a huge help as well.

Start with the composite-project build invoked by tsc --build packages and inspect how tsconfig.json project references relate to module resolution. Compare the existing --traceResolution and --explainFiles output paths. Done means compiler options report both missing references for imported packages and unused references, with behavior suitable for normal compilation.