typescript-docs-broken-cli-command

Answer

Root cause. The README instructed users to type-check a single file:

npx tsc --noEmit --skipLibCheck src/example.ts

This is broken in two ways, both verified against real tsc binaries:

1. TS5112 (TypeScript ≥ 6.0): when a tsconfig.json exists in the current directory, passing file names on the command line is an error — the config would be silently bypassed, so tsc refuses: error TS5112: tsconfig.json is present but will not be loaded if files are specified on commandline. Use '--ignoreConfig' to skip this error. On TS 5.x the same command exits 0 but silently ignores tsconfig.json, so examples get checked against the wrong compiler options (no strict, no project types, no skipLibCheck tuning) — a latent false-negative.
2. TS2591 via --ignoreConfig: the suggested escape hatch strips the project config, including "types": ["node"], so a CJS example using require.main === module fails even with @types/node installed: error TS2591: Cannot find name 'require'. Do you need to install type definitions for node? Try `npm i --save-dev @types/node` and then add 'node' to the types field in your tsconfig.

Fix (docs-only). Point the README at the project-wide invocation and state that examples are type-checked in the context of the project, not standalone.

README diff:

 ## Type-checking

-Run the compiler on a single example file:
+Run the compiler against the whole project from the repository root:

 ```bash
-npx tsc --noEmit --skipLibCheck src/example.ts
+npx tsc --noEmit
 ```

-The example compiles standalone, so `tsconfig.json` is ignored.
+This reads `tsconfig.json` (its `include`/`files` decide what is checked, and
+`strict`, `skipLibCheck`, and `types` come from the config). Do not pass
+individual file paths on the command line — TypeScript ≥ 6.0 rejects that
+combination with `TS5112`, and the `--ignoreConfig` workaround strips the
+project settings (e.g. `types: ["node"]`), which breaks CJS examples that use
+`require` with `TS2591`.
+
+Example snippets are part of the project and are checked in its context, not as
+standalone programs. In CI or a pre-commit hook, use the same command:
+
+```bash
+npx tsc --noEmit
+```

Key rules the corrected docs encode:

• Run from the project root where tsconfig.json lives.
• Never mix --project/existing config with explicit file arguments (that is exactly the TS5112/TS5110 class of error).
• Flags are only overrides, e.g. npx tsc --noEmit --skipLibCheck is fine without file arguments; the config already carries the project's settings.
• Snippets using Node globals (require, module) belong under the tsconfig's include with @types/node installed and "types": ["node"] (or left unset so all @types/* are auto-included); they are not standalone-compilable.