docs: rewrite the TypeScript fundamentals page#3250
Open
bartlomieju wants to merge 1 commit into
Open
Conversation
Lead with running a .ts file, explain the execution/checking split as the page's mental model, and add a Coming from Node.js section mapping tsx/ts-node/tsc/@types/node to their built-in Deno equivalents, covering the three things Node devs trip on: real file extensions in imports, full-language support vs erasable-only type stripping, and the absence of emit. Fixes a Deno 2 bug in the global augmentation examples: they augmented interface Window and accessed window.*, which type-checks but throws ReferenceError at runtime since window was removed in Deno 2; the page now declares globals with var and accesses them via globalThis. Also corrects the TSDoc label (the feature is TypeScript's JSDoc support), uses canonical JSDoc param order, documents deno check's directory and --check-js forms, and condenses the browser/worker lib material into a pointer at the configuration reference instead of duplicating it. Headings linked from other pages (#providing-declaration-files, #augmenting-global-types, #configuring-typescript-compiler-options, #tsconfig) are preserved.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
The TypeScript page never showed running a .ts file, buried the
execution-vs-checking mental model in a callout, and said nothing to its
most likely reader: a Node.js developer arriving with a tsc/tsx/ts-node
toolchain. It also taught a pattern that crashes on Deno 2 — the global
augmentation examples extend
interface Window, which type-checks butthrows
ReferenceError: window is not definedat runtime (verified),since
windowwas removed in Deno 2.This rewrite leads with
deno run main.ts, explains the strip-and-runvs opt-in-checking split up front (including that Deno never emits,
pointing at
deno transpile/deno pack), and adds a "Coming fromNode.js" section: a toolchain mapping table plus the three things Node
developers trip on — real file extensions in imports, full-language
support versus erasable-only type stripping, and emit options having
nothing to configure. The global augmentation examples now declare
globals with
varand access them viaglobalThis; the JavaScriptsection's "TSDoc" label is corrected to JSDoc with canonical syntax;
deno check's directory and--check-jsforms are documented; and thebrowser/worker lib material is condensed into a pointer at the
configuration reference instead of duplicating it. Every command and
claim was verified against Deno 2.8. Heading anchors linked from other
pages and all
oldUrlredirect entries are unchanged.