TypeScript Reference ยท Modules and Declaration Files
TypeScript JSDoc type annotations
Reference for typing JavaScript with JSDoc comments: @type, @param, @returns, @typedef, @template, @import and checkJs, with TypeScript equivalents.
You can have TypeScript check plain .js files by describing types in JSDoc comments. Turn on checkJs (or put // @ts-check at the top of a file) and the compiler reads tags such as @param, @returns, @type and @typedef as type annotations. No build step is needed to run the code, yet editors and tsc still report type errors, and tsc can generate .d.ts files from the comments.
The type syntax inside the braces is ordinary TypeScript, so everything you know about unions, generics and object types carries over. Only the place where it is written differs.
// @ts-check /** * @param {string} name * @param {number} [age] optional * @returns {string} */ export function greet(name, age) { return age === undefined ? `Hi ${name}` : `Hi ${name} (${age})`; }
Try it
A JavaScript file cannot be checked on this runner, so these examples are TypeScript versions of common JSDoc patterns with the JSDoc form in comments. The types and the behavior are identical.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or readFileSync(0)), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or readFileSync(0)), it gets the next line from this box.
Syntax
/** @type {Map<string, number[]>} */ const scores = new Map(); /** @typedef {"open" | "closed"} Status */ /** @typedef {import("./types.js").Config} Config */ /** @import { Config } from "./types.js" */ // TypeScript 5.5 and later /** @satisfies {Record<string, number>} */ /** @template {object} T */ /** @param {...string} parts */ /** @param {{ retries?: number }} [options] */ /** @overload */ /** @deprecated */ /** @readonly */ /** @enum {number} */
| Tag | Description |
|---|---|
@type {T} |
Type of the next variable, property or function expression. |
@param {T} name |
Parameter type. [name] or {T=} makes it optional; [name=default] gives a default. |
@returns {T} |
Return type. |
@typedef / @callback |
Declare a named type alias or function type. |
@template T |
Declare generic parameters; constraints go in braces. |
@import |
Import types without a runtime import. |
@satisfies |
Check a value against a type while keeping its inferred type. |
Edge cases: an unannotated function parameter in a checked .js file is implicitly any and is only an error when noImplicitAny is on. Types in braces must be valid TypeScript types; a typo becomes an error on the tag.
Usage notes
- Enable it with
"allowJs": true, "checkJs": trueintsconfig.json, or per file with// @ts-check. Opt a single file out with// @ts-nocheck, and a single line with// @ts-ignoreor// @ts-expect-error. - Generating types. With
allowJs,declarationandemitDeclarationOnly,tscproduces.d.tsfiles from JSDoc (Generating declarations). - Casts need parentheses around the expression:
/** @type {Foo} */ (expr). - Classes: declare fields with
@typeonthis.x = ...assignments in the constructor, or with class field syntax. - Limits: no
enum,namespaceor parameter-property syntax; some advanced type-level code is awkward in comments. - Good fit for small packages and scripts that should stay buildless. For larger projects most teams move to
.ts.