How JSDoc Saved My Dev Workflow

My default when starting a new project is TypeScript. It could be the smallest deliverable ever—like a single marketing webpage—and I’ll still whip out that TypeScript compiler in a flash. But what about when TypeScript isn’t an option? Maybe a build step isn’t feasible. Or it’s just a really short script and TS feels like overkill. Or maybe you’re handing off the code to someone who wants to make changes on the fly without worrying about compilation.

Okay, that last one is oddly specific… because it happened to me. I was writing a piece of code that wasn’t at its final destination and was likely going to be edited. I couldn’t guarantee the updated code would be run through tsc again, so I needed to ensure it remained readable and safe to modify. I won’t get into the details, but it’s safe to say TypeScript just wasn’t an option. 🙂‍↔️

This presented a big problem: I lost my red squigglies! I couldn’t hover over functions to see their signatures. And maybe worst of all—I lost my dev workflow of defining a function’s inputs and outputs before writing its implementation.

Enter JSDoc

How could I get back all that goodness without a build step? Well, you read the title: enter JSDoc, baby.

If you’re unfamiliar, JSDoc is an API documentation generator for JavaScript. It looks like this:

/**
* Represents a book.
* @constructor
* @param {string} title - The title of the book.
* @param {string} author - The author of the book.
*/
function Book(title, author) {
     //... code here
}

There can be more or less to it—think return types or just descriptions—but you get the idea. The best part? It’s just comments. No build step. No transpilation. Just good old inline documentation that powers your editor.

I first heard about JSDoc on an episode of JS Party 🪦 (RIP to my favorite podcast) when they discussed the TC39 Type Annotations proposal. JSDoc made headlines again when DHH ditched TypeScript in favor of JSDoc for Turbo 8.

Back to my problem: I remembered JSDoc existed and figured I’d give it a shot. Worst case? It would at least document my code better and help me return to my workflow of defining function I/O. But it actually took me way farther than I expected.

Turns out, the TypeScript compiler supports JSDoc! Even better? You know what popular IDE ships with tsc built-in? That’s right—it’s VS Code, baby 😎. All I needed was a bit of configuration, and I had hover tooltips, inferred types, and more.

You can enable type checking in one of two ways:

Option 1: Per-file opt-in

Add this comment to the top of your JavaScript file:

// @ts-check

Option 2: Project-wide config

Create a jsconfig.json in your root directory:

{
"compilerOptions": {
     "checkJs": true
   }
}

From there, I got greedy. Why stop at types? Why not get red squigglies too—without a build step? Enter: ESLint. By pairing ESLint with a JSDoc plugin and some well-chosen rules, I finally had my perfect squiggle setup.

I’ll cover the ESLint setup in another post—let me know if you’re interested!

Once I had ESLint checking my JSDoc annotations, I was off to the races. I immediately caught three or four real bugs that had slipped through earlier. Type checking was back. Dev workflow restored. No build step required.

JSDoc, here to save the day. Until next time 👋🏽 🫡