Your Node sample project should include a "lib" field to prevent incorrect recognition of DOM symbols

本报告涵盖已归档的 TypeScript-Node-Starter 项目和 TypeScript Website，其中网站重定向入口点已确定为 packages/typescriptlang-org/src/redirects/setupRedirects.ts。首先跟踪 /docs/home.html 和 /docs/home 的重定向规则，并将其与可正常工作的末尾带斜杠 URL 进行比较。完成后应包括一个已确认的重定向，该重定向能够到达文档且不会形成循环，而 Node starter 配置问题则需要单独的范围和负责人。

You have a github repo https://github.com/microsoft/TypeScript-Node-Starter . This project is the top hit for "Typescript Node sample code" on Google. This repo has multiple issues including a significant misconfiguration in the provided tsconfig.json, and a broken link to the main TypeScript documentation. The repo in question was "archived" one month ago and issues and PRs cannot be filed there.

The instructions for this repo say to file PRs instead of issues for non-critical documentation issues. Although I'm not sure I can honestly call the problems here "critical", I cannot file a PR because, again, the relevant repo is "archived".

Context/relevance

I am here because of this line of code:

const x = name;

Imagine writing a TypeScript program targeting Node, containing this line but not defining "name" first. TypeScript will not find an error. I encountered this in a project based on this one: https://github.com/mcclure/ts-hello-cmdline … but with TypeScript upgraded to newest 5.x (version is irrelevant here). (Can provide exact sample code on demand.) I was very, very surprised to find this program typechecking (because it uses an undefined symbol) and initially suspected I had misconfigured tsc. For this reason, I checked Google for Node sample code. I was happy to find the https://github.com/microsoft/TypeScript-Node-Starter project, which I assumed would be of high reliability due to being an official Microsoft repo. I found no differences between its configuration and mine, except the inclusion of "strict":true, which did not affect the problem line.

With the help of some nice people on "Mastodon", I learned the following:

• The code is, unfortunately, in some sense "correct" because there is (or was, I was told it was deprecated) a name field on document in the w3 DOM standard, and therefore the symbol is in lib.dom.d.ts. (I made some effort to find this field in the standard and failed. name turns out to be a difficult word to search for. Maybe in the current standard it's just been removed.)
• The code should still be treated as invalid in my situation because Node, being a non-web host environment, does not have the DOM. Running node at the command line and typing symbols like name, document or window gives you an unknown reference error. But! It turns out the reason TypeScript is treating my Node code as if DOM symbols were in scope is because I was not correctly using the lib configuration option in tsconfig (doc here) which exists for just this purpose.
• Adding "lib": ["es2020"], to my tsconfig.json fixes the problem and causes name to correctly be flagged as an undefined variable, without losing access to other ecmascript standard symbols like Set.

Having learned this, I immediately set out to make a PR for the TypeScript-Node-Starter repo adding the lib field so the next person to have this problem would have a better experience. As mentioned, this is not currently possible.

There is a second problem

Once I realized the TypeScript-Node-Starter repo was locked, I started examining the README to see if there was somewhere else I should be looking. For example when the https://github.com/microsoft/TypeScript-Handbook repo was closed there was a helpful, prominent note added to the repo description redirecting people to this repo here (TypeScript-Website). For TypeScript-Node-Starter there isn't, but there is this disclaimer at the top:

It is not a goal to be a comprehensive and definitive guide to making a TypeScript and Node project, but as a working reference maintained by the community. If you are interested in starting a new TypeScript project - check out the bootstrapping tools reference in the TypeScript Website

Perhaps I would find more at that link? In fact, the link in that paragraph is broken. If you go there, your browser will enter an infinite loop of redirecting to https://www.typescriptlang.org/docs/home, a blank white page consisting solely of a redirect to https://www.typescriptlang.org/docs/home. This is less helpful than it could be.

To summarize, I conclude there are three separate problems:

1. Your Node sample code is not adequately configured for Node, and the misconfiguration can cause subtle and frustrating problems of the exact type TypeScript exists to fix.
2. The link from your Node sample code to the main documentation is out of date.
3. Your website has a weird URL https://www.typescriptlang.org/docs/home.html that contains a faulty redirect to itself.

Additional notes

• I am actually not entirely sure "lib": ["es2020"], is the correct version of the ECMAScript library to opt into. One assumes different versions of Node will target different ES standard levels. The correct "lib" for a given Node version might in fact be some complex construction like ["es2016", "ES2019.Object", ES2019.String"] or I don't know what.. This is a point on which documentation or best-practices recommendations from TypeScript and/or Microsoft— for example in your highly-visible TypeScript-Node-Start project— would be very useful.
• My "problem 3" above actually I could theoretically file a PR on. I made an attempt to do so, but hit a dead end quickly. Searching the repo for "home.html", I find this file cataloguing the typescriptlang site's redirects, and I find /docs/home.html redirects to /docs/home and /docs/home redirects to /docs. The code looks correct and the problem appears to require more familiarity with your site code than I have. If it helps, we did find https://www.typescriptlang.org/docs/home/— in other words, the Weird URL but with a / at the end— correctly redirects to docs/.
• You might reply to this issue by saying that Node is not a Microsoft product and/or that TypeScript-Node-Starter is not an official/supported repo. If this happens to be the response, I want to repeat this repo is the top hit on Google* for "TypeScript Node sample project", and as a repo posted by the Microsoft account on Microsoft's code hosting site (GitHub) it presents the appearance of being very official. I would say it is a useful resource worth keeping maintained.

* On Bing, if you're wondering, it is the third hit. The first Bing hit is a page on NodeJS's website (the NodeJS document does not say anything about tsconfig lib) and the second is a tutorial posted in DigitalOcean's support pages (it suggests using "lib": ["es2015"]).