I finally understand TypeScript `outDir`, `include`, `exclude` configuration properties...

It took me a while to understand the behavior behind these TypeScript properties and that was driving me nuts at times. Every time I start a new project I forget what they are because you don't use them often, just when you set up your project scaffold. So that's why I write this small post, to remember.

Let's use this base for our examples

.
├── node_modules
├── src
│   ├── main.ts
│   └── test
│       └── a.ts
└── test

outDir

outDir is default to each individual file location. So for instance the compiler will output the file src/test/a.ts as src/test/a.js, quite simple.
It's important to understand that not using outDir or using "./" as its value is not the same thing !

include

include is default to ["**/*"] which translates to compile every ts files encountered recursively from the root (defined by the rootDir property).

Now here's the tricky part, when you don't use outDir the interpreter uses the full paths, so for instance the file src/test/a.ts (matched by src/**/*) will go in the same absolute path matched by src/**/* (therefore src/test/a.js).

But when you use outDir the wildcards are what is really interpreted by the compiler, so for instance when you use "outDir": "./" the file src/test/a.ts will go in the location matched by the wildcards in the expression src/**/* therefore prepended outDir ./ plus test/a.ts (not src/test/a.ts !), src here is not part of the match, it's just a reference to find the files.

exclude

Now you may ask, if the root is my project why won't ts files in node_modules get compiled as well ? The reason is because the default value of exclude is node_modules.

one example

If you want your compilation to have this final structure :

.
├── main.js
├── node_modules
├── src
│   ├── main.ts
│   └── test
│       └── a.ts
└── test
    └── a.js

you would use tsconfig.json like that

{
  "compilerOptions": {
    "outDir": "./"
  },
  "include": [ "src/**/*" ],
  "exclude": []
}