Typescript: please document project references and outdir

[breathe]

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 ...

> [email protected] 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]

It appears to me that outDir is essentially deprecated for projects using project references -- is that true? If not, can you offer even one example where these features will work in a sane way together?

[DanielRosenwasser]

Pretty sure outDir is evaluated relative to the original tsconfig.json. Each extending tsconfig.json should provide its own respective outDir

[breathe]

@DanielRosenwasser I've tried putting outDir in each of ./tsconfig.json, ./lib/pdf-api/tsconfig.json, and ./tsconfig_base.json -- the closest option to working is putting it in ./lib/pdf-api/tsconfig.json -- which creates the directory ./lib/pdf-api/compiled-js/src/... -- and also creates unwanted js files in ./lib/pdf-api/src/*/.js

[DanielRosenwasser]

You might just need to set the rootDir to avoid that extra level of src.

Maybe this repo will help a bit https://github.com/RyanCavanaugh/learn-a/

To be honest, maybe we just need an official sample repo of some sort.

[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]

Please do offer some better documentation around common usage patterns for this.

https://www.typescriptlang.org/docs/handbook/project-references.html sets up a great example of a project with source and test files but then never follows through to explain how tests with a project reference to the source they test should import those sources. Especially in the case where the developer wants to compile the source and test files to different outDirs.

[orta]

There are more docs on how the individual flags work in the v2 tsconfig reference: https://www.typescriptlang.org/v2/tsconfig

[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.