How to Write TypeScript Interfaces in JSDoc Comments

I like writing web apps without any build step, just vanilla .js files. But I still like the type-checking that TypeScript provides. Thankfully TypeScript supports type-checking .js files via JSDoc comments.

But how do you write out interfaces without a .ts file? Glad you asked.

Interfaces in a .ts file

First, let's look at an example in a .ts file.

interface Address {
  street: string;
  city: string;
  zip: number;
}

interface Customer {
  name: sting;
  email: string;
  address: Address;
}

Interfaces in a JSDoc comment

Writing those same interfaces in a .js file would look like:

/**
 * @typedef Address
 * @prop {string} street The street
 * @prop {string} city The City
 * @prop {number} zip The zip code
 *
 * @typedef Customer
 * @prop {string} name The Customer's name
 * @prop {string} email The Customer's email
 * @prop {Address} address The Customer's address
 */

And then you can apply that interface to an object using the @type annotation:

/** @type {Customer} */
const theCustomer = { ... }

Boom 💥 now you've got type-checking and intellisense on your data model right in a vanilla .js file.

Alternative: import interfaces from a .d.ts file

The other option to define interfaces is to put them in a .d.ts file and import that into you .js file.

// models.d.ts

export interface Address {
  street: string;
  city: string;
  zip: number;
}

export interface Customer {
  name: sting;
  email: string;
  address: Address;
}

And then in your .js file you can import those types:

/**
 * @typedef { import("./models").Customer } Customer
 */

 /** @type {Customer} */
const theCustomer = { ... }