Docs: adding a more prevalent notes about using custom typings and '-r ts-node/register' and clearifying what they do

[KilianKilmister]

currently, my types are missing includes this on it's final line:

Tip: If you must use files, include, or exclude, enable --files flags or set TS_NODE_FILES=true.

this is easily overlooked and issues and questions around this are posted regularly.

And while many of these are answered with the solution --files, this is not an option if the process is started via node -r ts-node/register (or for #1007 node --loader ts-node/esm.mjs ) and the only mention in these discussions of using an env-variable i found is from #866 (which i only found because of a small mention in whatever thetopsites.net is)

as noted in that issue:

• ts-node/register is only documented deep down in a comment thread accessible by searching for it and then it's only with a single sentence akin to "try this", so there's no documentation specifying the invariants I can expect to rely on when using it
• I read past --files in the docs multiple times during setting it up, but I'm not looking to specify multiple files, only the project file, which is what I am setting with TS_NODE_PROJECT; however, I now know that I also have to encourage it with TS_NODE_FILES=true.
• TS_NODE_FILES also confused me with the "files"-property in tsconfig.json

for the first paragrapg: while it is now mentioned a few times in the readme, it's still very much hidden behind specific usecases and this mention:

Note: If you need to use advanced node.js CLI arguments (e.g. --inspect), use them with node -r ts-node/register instead of the ts-node CLI.

is under the label of programmatic use which is largely unfitting since this is a shell command

for the second and third: this is still very much the case. since tsconfig has a 'files'-property that expects an array of files to include in the project, it is very misleading to use the same term for a toggle option. And this needs to be clearly stated in every paragraf talking about loading a tsconfig.json as 'loading a config' implies that the ts-compiler behaves the same with or without ts-node.
I would generally consider this less of a doccumentation flaw than a software flaw

As stated in my types are missing:

This requires that your type definitions be structured as type packages (not loose TypeScript definition files). More details on how this works can be found in the TypeScript Handbook.

The page in the provided link mentions "type package" exactly once

A types package is a folder with a file called index.d.ts or a folder with a package.json that has a types field.

And while that does explain it, it's easy to overlook. The term "types package" doesn't really exist. there is no reference to what it is on the first google search page and in the TypeScript Handbook search-bar it doesnt yield any related results.
the code example of a declaration file makes it seem like it just has to be a .d.ts-module

conclusion

I would consider this to be a high-priority issue, as it can form a major roadblock for using ts-node in a production-grade development environment.

[cspotcode]

Flags can also be specified within your tsconfig file: "ts-node": {"files": true}

[cspotcode]

Marked as "help wanted" to indicate that this is a good candidate for a pull request.

A few notes:

1. native ESM support in node itself is still experimental, so our support is still experimental as well. (if node makes breaking changes, they might break us) While it is experimental, I'd like to the keep the native ESM docs out of our README and in ESM support: soliciting feedback #1007.
2. We can add a node -r ts-node/register example to the code block in https://github.com/TypeStrong/ts-node#shell
3. We can add a link from https://github.com/TypeStrong/ts-node#shebang to https://github.com/TypeStrong/ts-node#options-via-tsconfigjson, telling users to put CLI flags in their tsconfig when using a shebang.
4. We can clarify, in https://github.com/TypeStrong/ts-node#help-my-types-are-missing, what exactly ts-node is doing to "files", "include", and "exclude". We are basically setting those to empty arrays, except we put your entry-point into the "files" array. Should be easy to have an example of this, so users can setup their tsconfig like this manually and see what tsc does with it.

[KilianKilmister]

Flags can also be specified within your tsconfig file: "ts-node": {"files": true}

ah, missed that part. would probably be a good idea to put it on top of the description-list.

• native ESM support in node itself is still experimental, so our support is still experimental as well. (if node makes breaking changes, they might break us) While it is experimental, I'd like to the keep the native ESM docs out of our README and in ESM support: soliciting feedback #1007.

i figured. i added a comment about including a note for that on #1007

[cspotcode]

Closing because I doubt anyone will send us a PR for this, and I touched up the docs in #1682, so this is probably fixed.