There are two levels of TypeScript configuration files within the monorepo: root-level and package-level. In both cases, configurations can contain a references field. This field allows TypeScript to create a dependency tree of the the whole monorepo so if a package relies on another package's types, it knows to build the second package before the first. Hence, it is important that these references be correct, otherwise the monorepo will fail to build, or it will succeed but packages may not work correctly in production.

On top of this, there are actually two kinds of TypeScript configuration files per level, one called tsconfig.json and the other called tsconfig.build.json. The reason we have two variants is that the build-specific one omits test files and other files we do not want to include in the build, whereas the other one does not (this way tsserver "sees" every TypeScript file in development). The per-package configuration files extend from the root configuration files. The configurations are easy to manage if the two variants look similar.

Unsurprisingly, it is easy and common for the TypeScript configuration files to be misconfigured. We should have a step in the linting process that validates them and notifies the developer if anything looks wrong (particularly the references).

At the project level, the following should hold true:

• In tsconfig.json, references should cover all public workspace packages, and all paths should point to valid files and end with /tsconfig.json [note: this is not the case now but we can add it for consistency with the next rule]
• In tsconfig.build.json, references should cover all public workspace packages, and all paths should point to valid files and end with /tsconfig.build.json.

For each public workspace package, the following should hold true:

• tsconfig.json should be present and:
  • extends should be "../../tsconfig.packages.json"
  • compilerOptions.baseUrl should be "./"
  • if the package has any dependencies or peerDependencies that refer to workspace packages, references should correspond to all dependencies, and all paths should end with /tsconfig.json [note: this is not the case now but we can add it for consistency with the next rule]
  • if the package has no dependencies or peerDependencies that refer to workspace packages, then references should not exist
  • include should include "../../types" and "./src", and should be sorted alphabetically
• tsconfig.build.json should be present and:
  • extends should be "../../tsconfig.packages.build.json"
  • compilerOptions.baseUrl should be "./"
  • compilerOptions.dist should be "./dist"
  • compilerOptions.rootDir should be "./src"
  • if the package has any dependencies or peerDependencies that refer to workspace packages, references should correspond to all dependencies, and all paths should end with /tsconfig.build.json
  • if the package has no dependencies or peerDependencies that refer to workspace packages, then references should not exist
  • include should include "../../types" and "./src", and should be sorted alphabetically