How to Write TypeScript Interfaces in JSDoc Comments

Interfaces defined in jsdoc comment

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 = { ... }

Importing from .d.ts file

Hopefully you found this post helpful, if you have any questions you can find me on Twitter.

Make Your Resume Stand Out with Highlights
Enabling Emoji Shortcodes in Eleventy Markdown Files