What do the `// @ts-check` and `// @ts-nocheck` comments do when placed at the top of a file, and how do they interact with TypeScript's `checkJs` compiler option?

## The setting is global, the decision is per file `checkJs` in `tsconfig.json` says "report type errors in JavaScript files". But the compiler ultimately asks the question one file at a time, and two magic comments answer it directly, overriding whatever the project said. ## // @ts-check Put it as a comment at the top of a `.js` file, before any statements: ```js // @ts-check /** @param {string} name */ export function greet(name) { return name.toUpperCase(); } greet(42); // error: Argument of type 'number' is not assignable to parameter of type 'string'. ``` That file is now checked. Nothing about its neighbours changes. The diagnostics are the ordinary TypeScript diagnostics, derived from whatever the compiler can infer plus any JSDoc types the file declares — remember a `.js` file has nowhere to write type syntax, so JSDoc is the only channel for explicit types. Two things about it are worth being precise on. First, for a `tsc` build the file still has to be *in the program* — `allowJs` is what admits `.js` files, and a comment cannot admit a file the compiler never looks at. Second, an editor using the TypeScript language service will honour the comment on a loose file with no project at all, which is why `// @ts-check` is such a common first move: you get real feedback in the editor before touching any configuration. ## // @ts-nocheck The mirror image. At the top of a file, it suppresses the type errors the checker would report in that file: ```js // @ts-nocheck // legacy vendor bundle - not worth annotating ``` Two details matter. It works in TypeScript files as well as JavaScript ones — a `.ts` file with `// @ts-nocheck` at the top stops reporting errors too. And its scope is exactly one file: it does not propagate to imports, and it does not stop other files from complaining about *this* file's exported shapes. Types are still inferred and still flow outward to consumers; only the diagnostics inside the file are silenced. ## Placement Both are comments at the top of the file, ahead of code. A directive buried halfway down does nothing, which is a surprisingly common bug report — the file simply is not checked, or is still checked, and nothing explains why. They are `//` line comments (or block comments); they are not JSDoc tags, so they do not belong inside a `/** ... */` attached to a declaration. ## Why both exist: two rollout shapes **Opt in.** Leave `checkJs` off. Add `// @ts-check` to a file when you touch it, fix what it finds, commit. Nothing else in the repo can break. The cost is that a new untouched file is unchecked by default, so coverage only grows where people happen to work. **Opt out.** Turn `checkJs` on for the whole project and add `// @ts-nocheck` to the files that produce unmanageable noise. Now the default is safe: a new `.js` file is checked from the moment it exists, and the exemptions are visible in the diff and greppable. The cost is a bigger initial push. The opt-out shape is the stronger end state for exactly the reason that makes `@ts-expect-error` better than `@ts-ignore`: an explicit, greppable suppression list decays visibly, while an implicit "not opted in yet" default is invisible. ## What they are not They are file-level switches, not error suppressors for a line — that is `// @ts-expect-error` and `// @ts-ignore`, which target the next line only. And neither has any effect on emit: a `// @ts-nocheck` file is still compiled and still output. They move diagnostics, nothing else.