0Pricing
TypeScript Academy · Lesson

JSDoc Type Annotations as a Bridge

Add types to JS files using JSDoc before converting.

JSDoc Type Annotations as a Bridge is a free TypeScript Academy lesson on CoddyKit — lesson 2 of 4. You can read the complete lesson below for free — then practise it hands-on in the browser with a built-in code editor and a 24/7 AI tutor. It is part of the TypeScript Academy learning path, one of 4 lessons in the course, and your progress syncs across the web and the CoddyKit app.

JSDoc as a TypeScript Bridge

TypeScript can read JSDoc type annotations in JavaScript files when checkJs: true is enabled. This lets you add types to JS without renaming files.

/** @type {string} */
let name = "Alice"; // TypeScript checks this as string

@param and @returns

Annotate function parameters and return types using JSDoc tags.

/**
 * @param {string} name
 * @param {number} age
 * @returns {string}
 */
function greet(name, age) {
  return `${name} is ${age}`;
}

@typedef for Object Types

Use @typedef to define reusable type aliases in JSDoc.

/**
 * @typedef {Object} User
 * @property {string} id
 * @property {string} name
 * @property {boolean} isActive
 */

/** @type {User} */
const user = { id: "1", name: "Alice", isActive: true };

@template for Generics

Use @template to write generic functions in JSDoc.

/**
 * @template T
 * @param {T[]} arr
 * @returns {T | undefined}
 */
function first(arr) {
  return arr[0];
}
// TypeScript infers: first<T>(arr: T[]): T | undefined

Importing Types from .ts Files

JSDoc supports @type {import("./types").User} to import TypeScript types into JS files.

/** @type {import("./types").User} */
const admin = { id: "admin", name: "Admin", isActive: true };

@ts-check for Per-File Checking

Add // @ts-check at the top of a JS file to enable TypeScript checking for that file only, without checkJs: true globally.

// @ts-check
/** @type {number} */
const count = "oops"; // Error: string not assignable to number

@ts-ignore and @ts-expect-error

Suppress specific JSDoc type errors with inline directives without disabling the whole file.

// @ts-ignore
const x = badFunction(); // single error suppressed

// @ts-expect-error
const y = anotherBad(); // error expected here

JSDoc Enums

Simulate TypeScript enums in JSDoc using @enum.

/** @enum {string} */
const Direction = { Left: "left", Right: "right", Up: "up" };

Type Assertions in JSDoc

Use /** @type {SomeType} */ (expression) for JSDoc type assertions, equivalent to TypeScript's as SomeType.

const el = /** @type {HTMLInputElement} */ (document.getElementById("input"));
el.value; // el: HTMLInputElement — typed

When to Move to .ts

JSDoc annotations are a bridge, not a destination. Once a file is fully annotated and stable, rename it to .ts and remove the JSDoc type comments in favor of native TypeScript syntax.

// Rename: utils.js → utils.ts
// Replace JSDoc: /** @param {string} x */ → (x: string)

Recap: JSDoc as Bridge

JSDoc type annotations enable TypeScript checking in JS files without renaming them. Use @type, @param, @typedef, and @template to add type safety incrementally before converting to native TypeScript.

Quick Check

Which JSDoc tag enables TypeScript checking in a single file without global checkJs?

What You Learned

JSDoc type annotations bridge JavaScript and TypeScript: use @type, @param, @typedef, and @template to add types to JS files. Enable per-file checking with // @ts-check, then convert to native TypeScript when ready.

Frequently asked questions

Is the “JSDoc Type Annotations as a Bridge” lesson free?

Yes — the full text of “JSDoc Type Annotations as a Bridge” is free to read here on the web, and the TypeScript Academy course includes 4 lessons in total. To practise it interactively (a built-in code editor and a 24/7 AI tutor) and unlock the rest of the TypeScript Academy course, upgrade to CoddyKit PRO.

What will I learn in “JSDoc Type Annotations as a Bridge”?

Add types to JS files using JSDoc before converting. You practise TypeScript Academy with hands-on code you run directly in the browser, and a 24/7 AI tutor answers your questions as you work through the lesson.

Do I need any experience to start TypeScript Academy?

No prior experience is required. TypeScript Academy on CoddyKit is structured for beginners through advanced learners; this is — lesson 2 of 4, so you can start here or from the beginning and move at your own pace.

How long does the “JSDoc Type Annotations as a Bridge” lesson take?

Most CoddyKit lessons take about 5–10 minutes. Each one is bite-sized and interactive, so you make steady progress and pick up exactly where you left off across the web and the app.

Can I write and run code in this TypeScript Academy lesson?

Yes. Every TypeScript Academy lesson includes a built-in code editor, so you write and run real code right in your browser and get instant AI feedback — no local setup required.

All lessons in this course

  1. Starting the Migration: allowJs and checkJs
  2. JSDoc Type Annotations as a Bridge
  3. File-by-File Conversion Strategy
  4. Dealing with Untyped Third-Party Libraries
← Back to TypeScript Academy