harmonize TypeScript configs

[turadg]

What is the Problem Being Solved?

Each package has its own TypeScript configuration. This entails that typechecking the repo requires typechecking each package, which repeats checks over transitive imports. That's a contributor to,

• linting is too slow #2621

Description of the Design

Harmonize the TypeScript configs so there is one master configuration. Each package can be typechecked at will, but the repo as a whole can also be typechecked with one tsc.

This is distinct from but a step towards unifying ESlint similarly.

Security Considerations

Scaling Considerations

Test Plan

Types building for export is still per package. Existing CI verifies that each package can build its types and pack.

Compatibility Considerations

Upgrade Considerations

[boneskull]

Ref: #2621 (comment)

[boneskull]

Regarding design for something like this, I'd suggest going in this direction (though it's just a suggestion and we've already implemented some similar stuff):

• .config/tsconfig.common.json
  • containing all compilerOptions common to all workspaces in the entire monorepo
  • compilerOptions such as allowJs: true, checkJs: true, types: ['node']
  • should contain all the compilerOptions in tsconfig.eslint-base.json currently;
  • should not contain files, include, nor exclude
• .config/tsconfig.refs.json
  • references to each packages/*/tsconfig.json in descending order; roughly from most-depended-upon [libraries] to least-depended-upon [apps])
  • should contain nothing else
• packages/*/tsconfig.json:
  • workspace-specific configuration
  • extends ../../.config/tsconfig.common.json
  • contains references to all other workspaces it depends upon (critical for incremental builds); include both sources and tests (ideally)
  • any workspace-specific compilerOptions should live here (e.g., outDir, types)
  • should not contain output-related compilerOptions (e.g., noEmit) since those are controlled by configs at the workspace root
  • declarations generated from test files can be excluded from publish via the files field of package.json
  • optionally, this could contain references to relative ./src/tsconfig.json and ./test/tsconfig.json configs having different configurations for source code and tests, respectively; useful if you need some specific types for a test framework, but I don't think we need it.
  • you may need to use the paths compilerOption if TS is unable to understand dependencies between workspaces. It could help resolution of types if workspace A depends on B, but B has not yet emitted declarations), but I'm not optimistic.
• tsconfig.build.json
  • containing build-specific output-related compilerOptions (e.g., emitDeclarationOnly: true, declarationMap: true)
  • this will be the entrypoint to tsc -b for builds during development and prior to publish
  • extends .config/tsconfig.common.json and .config/tsconfig.refs.json
  • should contain files: []
  • should not contain include nor exclude
• tsconfig.json
  • for tooling (eslint and IDEs)
  • will have compilerOptions noEmit: true
  • otherwise identical to tsconfig.build.json
  • should contain files: [] and should not contain include nor exclude

A hazard can be cyclic references which are not otherwise surfaced at runtime. For example, package A depends on B but B depends on a type from A.

A dev script in the workspace root should be tsc -b tsconfig.build.json --watch. 😄