PricingLoginStart free
TypeScript Academy · Lesson

JSDoc Type Annotations as a Bridge

Add types to JS files using JSDoc before converting.

Lesson 2 of 413 steps

JSDoc Type Annotations as a Bridge is a free TypeScript Academy lesson on CoddyKit. This is 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, and your progress syncs across the web and the CoddyKit app. The TypeScript Academy course includes 4 lessons in total.

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?

Answer it in the interactive lesson

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.

Free to start

Learn TypeScript with an AI tutor — free

Write and run real code in your browser, get instant help from a 24/7 AI tutor, and pick up where you left off on the web or in the app.

Courses
101
Lessons
352
Start learning freeView the full course

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. 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. The TypeScript Academy course includes 4 lessons in total.

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, so you can start here or from the beginning and move at your own pace. This is lesson 2 of 4.

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