Prettier Plugin for JSDoc Type Annotations

0.2.0 verified Sat Apr 25 auth: no javascript

A Prettier plugin that formats JSDoc type annotations to match a consistent TypeScript style. Current stable version is 0.2.0, released in early 2025. It focuses solely on JSDoc type syntax (e.g., @type, @param, @returns, @import) unlike broader JSDoc formatting tools. Supports object types, arrays, unions, function types, and complex constructs like @import with aliases and @returns {foo is Foo}. Requires Prettier >=3.5.3 and TypeScript as peer dependencies. Actively maintained with frequent patches fixing edge cases in type parsing.

Common errors

error Cannot find module 'prettier-plugin-jsdoc-type' ↓

cause Plugin not installed or peer dependencies missing.

fix

Run npm install --save-dev prettier-plugin-jsdoc-type prettier@>=3.5.3 typescript

error Error: Cannot find module 'typescript' ↓

cause TypeScript is a peer dependency but not installed.

fix

Install TypeScript: npm install --save-dev typescript

error Configuration error: Could not resolve plugin "prettier-plugin-jsdoc-type" ↓

cause Prettier configuration file (e.g., .prettierrc) references plugin incorrectly.

fix

Ensure .prettierrc contains: { "plugins": ["prettier-plugin-jsdoc-type"] }

error JSDoc type formatting not applied ↓

cause Prettier might be using a parser that doesn't handle JSDoc (e.g., babel instead of typescript).

fix

Set parser to 'typescript' in Prettier config or use proper file extension (.ts/.tsx).

Warnings

breaking Plugin may produce formatting incompatible with older Prettier versions (requires Prettier >=3.5.3). ↓

fix Upgrade to Prettier >=3.5.3 and plugin >=0.2.0.

deprecated The plugin does not handle JSDoc comments (description, tags); use prettier-plugin-jsdoc for that. ↓

fix Consider using prettier-plugin-jsdoc alongside if you need full comment formatting.

gotcha Plugin is experimental; may not support all JSDoc type syntax edge cases. ↓

fix Test thoroughly; report issues on GitHub.

gotcha Plugin only formats JSDoc type annotations inside comments, not TypeScript types in code. ↓

fix Ensure you are not expecting TypeScript code formatting from this plugin.

gotcha Plugin might conflict with other Prettier plugins if they also transform JSDoc or comments. ↓

fix Run Prettier with this plugin alone to isolate issues, or check plugin ordering.

Install

npm install prettier-plugin-jsdoc-type

yarn add prettier-plugin-jsdoc-type

pnpm add prettier-plugin-jsdoc-type

Imports

plugin

wrong

// In .prettierrc: { "plugins": ["prettier-plugin-jsdoc"] }

correct

// In .prettierrc: { "plugins": ["prettier-plugin-jsdoc-type"] }

This is a separate plugin from prettier-plugin-jsdoc; both can be used together.

default

wrong

import prettierPluginJsdocType from 'prettier-plugin-jsdoc-type'

correct

// No direct import; configure via Prettier config

Plugin is not imported in code; it is loaded by Prettier via the plugins array in configuration.

require
wrong
```
const plugin = require('prettier-plugin-jsdoc-type')
```
correct
```
// Not applicable; use Prettier config file
```
CommonJS require is not the intended use; the plugin is only for Prettier configuration.

Quickstart

Installation, configuration, and example formatting of JSDoc type annotations including object types, unions, @import, and @returns with type predicates.

// Install
npm install --save-dev prettier prettier-plugin-jsdoc-type typescript

// .prettierrc
{
  "plugins": ["prettier-plugin-jsdoc-type"],
  "parser": "typescript"
}

// Input file: example.js
/** @type {{a?:number,b?:string}} */
const obj = {};

/**
 * @param {{
 * type?:string,
 *  a?:number
 *   b?:string}} n
 * @returns {n   is Foo}
 */
function fn(n) {
  // do something
}

/** @import {Foo}from'bar' */

// After formatting with Prettier:
// /** @type {{ a?: number; b?: string }} */
// const obj = {};
//
// /**
//  * @param {{
//  *   type?: string;
//  *   a?: number;
//  *   b?: string;
//  * }} n
//  * @returns {n is Foo}
//  */
// function fn(n) {
//   // do something
// }
//
// /** @import { Foo } from "bar" */