3 ms·

Many people in this thread are rightly complaining that this does not answer the "why does this work". Having a working example is a good start for that though

by koolba 3y ago

Many people in this thread are rightly complaining that this does not answer the "why does this work". Having a working example is a good start for that though as at least you have a known target and as you change things (and break things), you can see what those options did. One problem with this guide that makes that trickier is that the tsconfig.json itself imports https://github.com/sindresorhus/tsconfig/blob/5c87dc118e057dc16fe1e62c990645000dbfaac7/tsconfig.json 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: "compilerOptions": { // ... "module": "node16", "moduleResolution": "node16", "moduleDetection": "force", // ... "allowSyntheticDefaultImports": true, // To provide backwards compatibility, Node.js allows you to import most CommonJS packages with a default import. This flag tells TypeScript that it's okay to use import on CommonJS modules. "jsx": "react", // ... } 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.

btown 3y ago
https://documentation.divio.com/ https://documentation.divio.com/ is a good overview of the "four types of documentation" paradigm: tutorials, how-to guides, explanations, and reference have to all exist. One of my major gripes with the JS/TS ecosystem is that "explanations" are sorely lacking. See https://www.typescriptlang.org/tsconfig 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-demystified-d8f333e578c1 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/bca2fda868c1e8b2c2caf76af7dfcad3 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!
- paddy_m 3y ago
  What programming languages and libraries are well explained in this aspect?
  - Macha 3y ago
    Python, Rust. Given that Python was one of the first open source projects to choose such a model, and Rust explicitly adopted such a model, that's probably not so surprising. (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)
- mst 3y ago
  I once did a conference talk on the different types - called it Euclid, Socrates and Mill and analogised a good tutorial to Euclid's Elements, the explanation part to Socrates and howto/cookbook type stuff to John Stewart Mill. (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 ;)
- mook 3y ago
  It's not even that great, typescript doesn't even have a good reference. There are random features that are only documented on release notes. Working with TS has been somewhat frustrating.
- jakebailey 3y ago
  > One of my major gripes with the JS/TS ecosystem is that "explanations" are sorely lacking. See https://www.typescriptlang.org/tsconfig 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. 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/introduction.html 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.
jakjak123 3y ago
I am struggling with this just now. I am however writing a library where it makes sense to allow import of subpaths. How would this change then?

by koolba 3y ago

btown 3y ago

https://documentation.divio.com/ https://documentation.divio.com/ is a good overview of the "four types of documentation" paradigm: tutorials, how-to guides, explanations, and reference have to all exist. One of my major gripes with the JS/TS ecosystem is that "explanations" are sorely lacking. See https://www.typescriptlang.org/tsconfig 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-demystified-d8f333e578c1 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/bca2fda868c1e8b2c2caf76af7dfcad3 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!

paddy_m 3y ago
What programming languages and libraries are well explained in this aspect?
- Macha 3y ago
  Python, Rust. Given that Python was one of the first open source projects to choose such a model, and Rust explicitly adopted such a model, that's probably not so surprising. (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)
mst 3y ago
I once did a conference talk on the different types - called it Euclid, Socrates and Mill and analogised a good tutorial to Euclid's Elements, the explanation part to Socrates and howto/cookbook type stuff to John Stewart Mill. (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 ;)
mook 3y ago
It's not even that great, typescript doesn't even have a good reference. There are random features that are only documented on release notes. Working with TS has been somewhat frustrating.
jakebailey 3y ago
> One of my major gripes with the JS/TS ecosystem is that "explanations" are sorely lacking. See https://www.typescriptlang.org/tsconfig 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. 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/introduction.html 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.

jakjak123 3y ago

I am struggling with this just now. I am however writing a library where it makes sense to allow import of subpaths. How would this change then?