please document project references and outdir

Really really unclear documentation regarding the behavior of “project references” and outDir.

I can’t believe how unclear this is – please please tell me how I’m supposed to do this …

> checkmate-node-monorepo@0.0.1 build /Users/ncohen/software/itsacheckmate.com/Web
> tsc --build --verbose

[11:01:04 AM] Projects in this build:
    * lib/pdf-api/tsconfig.json
    * tsconfig.json

[11:01:04 AM] Project 'lib/pdf-api/tsconfig.json' is out of date because output file 'lib/pdf-api/src/DoordashFailureSamples.js' does not exist

[11:01:04 AM] Building project '/Users/ncohen/software/itsacheckmate.com/Web/lib/pdf-api/tsconfig.json'...

[11:01:07 AM] Project 'tsconfig.json' is out of date because oldest output 'lib/pdf-api/src/DoordashPdfSemantics.js' is older than newest input 'lib/pdf-api'

[11:01:07 AM] Building project '/Users/ncohen/software/itsacheckmate.com/Web/tsconfig.json'...

[11:01:09 AM] Updating unchanged output timestamps of project '/Users/ncohen/software/itsacheckmate.com/Web/tsconfig.json'...

ncohen@breathe-book ~/s/i/Web> cat tsconfig.json
{
  "references": [{ "path": "./lib/pdf-api" }]
}

ncohen@breathe-book ~/s/i/Web> cat ./lib/pdf-api/tsconfig.json
{
  "extends": "../../tsconfig_base.json",
  "include": ["./src/**/*.ts"],
  "exclude": ["node_modules"]
}

ncohen@breathe-book ~/s/i/Web> cat ./tsconfig_base.json
{
  "compilerOptions": {
    "composite": true,
    "outDir": "compiled-js",
    "target": "es2016",
    "lib": ["es2016"],
    "module": "commonjs",
    "moduleResolution": "node",
    "sourceMap": true,
    "experimentalDecorators": false,
    "pretty": true,
    "strict": true,
    "strictFunctionTypes": true,
    "noFallthroughCasesInSwitch": true,
    "noImplicitAny": true,
    "noImplicitReturns": true,
    "forceConsistentCasingInFileNames": true,
    "strictNullChecks": true,
    "declaration": true,
    "declarationMap": true
  }
}

Why are compiled files being written to ./lib/pdf-api/src/ directory? How can I have that NOT happen? Or if I have to have something written to my src directory (for some reason …?) can I have only a single file written there which I can reliable gitignore …?

ncohen@breathe-book ~/s/i/Web> tsc --version
Version 3.5.2

[breathe]

Thanks @DanielRosenwasser – using that example I was able to get going correcty.

The behavior of this feature with respect to rules like outDir and rootDir is pretty confusing – official documentation of the feature via example repo’s would seem a nice approach to me!

[jonah-williams]

The individual flag documentation is great but I find that it’s a lot of work to try to infer from those what a reasonable project setup looks like. Having guidelines here could help projects adopt these features and set conventions.

For example my first reaction was to build a project something like:

┣ src
┃    ┣ module.ts
┃    ┗ tsconfig.json //"outDir": "../dist",
┣ dist
┃    ┣ module.js
┃    ┗ src.tsbuildinfo
┣ test
┃    ┣ test.ts // import * from "../src/module"
┃    ┗ tsconfig.json // "outDir": "../tmp",
┗ tmp
     ┣ test.js
     ┗ test.tsbuildinfo

but I was then surprised to find that my test file had to use import * from "../dist/module" rather than import * from "../src/module" despite having project references in place. It wasn’t clear to me if that was a sign of a misconfigured project, incorrect expectations for how these features work, or something else.