One of my major gripes with the JS/TS ecosystem is that "explanations" are sorely lacking. See https://www.typescriptlang.org/tsconfig for the relevant documentation for tsconfig files. Tutorials are on the page, how-to guides abound on the wider internet (like the OP), and the linked TSConfig Reference and JSON Schema (used in code completion in IDEs) are together absolutely massive.
But an explanation is missing! There is no official documentation about how different options interact to say: as I'm walking a file tree as the Typescript compiler, this is how I will interpret a certain file I encounter, what will be outputted, and how that will be interpreted by bundlers and browsers, especially in an ESM world.
https://medium.com/extra-credit-by-guild/tsconfig-json-demys... is in the right direction, but outdated as ESM has become much more popular in the past 3 years, and still organized by option (so it's already somewhat in the "reference" world).
IMO even independent of documentation, the industry's move to ESM is problematic: https://gist.github.com/joepie91/bca2fda868c1e8b2c2caf76af7d... describes many of the issues. But they're certainly exacerbated by good explanation-style documentation that helps people understand how ESM works under the hood!
Working with TS has been somewhat frustrating.
(don't remember if there's a decent video out there but I figure you probably don't need to listen to me waffle to see how the analogies might work ;)
(Somebody is going to bring up the Python packaging clusterfuck as a retort to this, but the fact that Python packaging is both assumed and held at a distance is a larger problem than just documentation)
> But an explanation is missing! There is no official documentation about how different options interact to say: as I'm walking a file tree as the Typescript compiler, this is how I will interpret a certain file I encounter, what will be outputted, and how that will be interpreted by bundlers and browsers, especially in an ESM world.
Perhaps you missed it, but Andrew (from the TS team) recently finished a massive overhaul of our module docs: https://www.typescriptlang.org/docs/handbook/modules/introdu...
The "theory" page describes TypeScript's perspective on modules. The "reference" page documents things from the "as I'm walking a file tree" perspective (among many other details). The "guides" page also provides recommendations for certain kinds of projects.
One problem with this guide that makes that trickier is that the tsconfig.json itself imports https://github.com/sindresorhus/tsconfig/blob/5c87dc118e057d... and overrides a bunch of values.
So if you really want to understand what it's doing, you need to get rid of that dependency and inline / merge that config file. That would also add stability to your project as it's one less upstream dependency out of your control (and a big one at that as it controls how you entire project is built!).
For example the imported tsconfig.json changes these:
But you wouldn't notice that if you just look at the gist. It'd just be a magic that you can write React code in a .tsx file. Clearly that has to be enabled somewhere.