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