Create an explainer / hub page for type stripping (TypeScript) support

[JoshuaKGoldberg]

Enter your suggestions in details:

The new type stripping / TypeScript support in Node.js is very exciting. A lot of users are adopting the built-in support for both source code and tooling config files. 🚀

But, there isn't one single high-level, official resource that users can be pointed to to understand the unflagged support.

• https://nodejs.org/en/learn/typescript/run-natively is more of a runbook that shows how to use it, but doesn't explain much of the concepts. It's also out of date now that support is no longer experimental.
• https://satanacchio.hashnode.dev/everything-you-need-to-know-about-nodejs-type-stripping is not official. It feels weird pointing folks to a third party platform. It also has a lot of details on historical context and decision-making that users who just want to learn the high level of the feature wouldn't want to have to read through. (it is a great blog post on its own though!)
• https://nodejs.org/api/typescript.html#type-stripping is very technical and dives into the weeds of the module system.

Proposal: can the Node.js site have a page added dedicated to explaining type stripping at the high level? I'd imagine it could contain:

1. What "type stripping" is
2. Quick examples of running a .ts file
3. What versions of Node.js have it
4. Quick FAQs such as un/not-yet-supported syntax and type checking
5. Links to learn more on the official Node.js and TypeScript websites

Sibling issue to #7441, intentionally with as similar an issue body as possible.

[AugustinMauroy]

cc @marco-ippolito

[marco-ippolito]

No objections from my side, I agree a detailed guide would be useful. It has been moving pretty quickly and now its slowing down, so it should be possibile to write something without it becoming outdated immediately

[AugustinMauroy]

Can I work on this or someone want work onto it ?

[AugustinMauroy]

Okay after re-read of whole typescript sub-section:

• learn/typescript/transpile: should have explaining about tsconfig and what transpiling can be interesting (mainly choosing the target).
• learn/typescript/run: we should add why this method exist and what is interesting for user to use this method.
• learn/typescript/run-natively has been created just after the landing of "types-stripping" so we need some new thing
  • Why node didn't have any kind of config
  • JSX + TSX what is it why node didn't handle this (basically no config + depend of the target).
  • Why/what is type-stripping

Other point

• The order need to be changed introduction => run natively ('cause it's the easiest way no conf just run) => transpiling => extra thing with runner
• #7279 explain how to publish a ts package to npm registry. But how should we advise working with typescript when it's not a package, I mean when it's directly a project. IMO native run for dev + tsc transpiling for prod.
• there is no mention of type definition, for example there is no mention of @types/node.

Extra thing just to keep trace/ personal note

• https://github.com/nodejs/nodejs.org/blob/317dce61aaaf9e1fb241edc8cac72884e745ac8b/apps/site/pages/en/learn/typescript/transpile.md?plain=1#L9 this should be rephrased because "node can run typescript".

[AugustinMauroy]

After sync with Jacob:

Here is the logic/link between the articles and the order in which they should appear

• Intro:
  • add info about type defs (ex @types/node)
  • jsx
• Running:
  • in dev
  • in prod
    • don’t → pre-compile. link back to dev compile option with diff codeblock for prod settings (ex minify: true)
• Publishing for distribution:
  • down-versioning

So action will be:

1. revise intro
2. finish Publishing a TypeScript project
3. Reviese order and logic between article (explain above)

[avivkeller]

Is this resolved, we have several articles for TS now?

[avivkeller]

(oops, wrong button)

[marco-ippolito]

I think https://nodejs.org/en/learn/typescript/run-natively would still benefit a more in depth explanation