prettier-plugin-jsdoc

1.8.0 verified Sat Apr 25 auth: no javascript

A Prettier plugin (v1.8.0) that formats JSDoc comment blocks, converting them to a consistent style. Written in TypeScript, requires Prettier ^3.0.0 and Node >=14.13.1. It supports standard JSDoc tags, Markdown in descriptions, @example code blocks, TypeScript type definitions, and React prop types. Unlike alternative formatters (e.g., eslint-plugin-jsdoc), this integrates directly with Prettier as a plugin, ensuring zero-config formatting in editors and CI. Actively maintained with frequent releases.

Common errors

error Error: Cannot find module 'prettier-plugin-jsdoc' ↓

cause Plugin not installed or not resolved by Prettier.

fix

Run: npm install --save-dev prettier-plugin-jsdoc

error Error: Requires Prettier >= 3.0.0 ↓

cause Installed Prettier version is too old.

fix

Upgrade Prettier: npm install prettier@latest --save-dev

error TypeError: prettier-plugin-jsdoc is not a function ↓

cause Incorrectly trying to import the plugin as a module instead of configuring it in .prettierrc.

fix

Remove any import of prettier-plugin-jsdoc from code; add it to Prettier config plugins array.

Warnings

breaking prettier-plugin-jsdoc v1.0.0 requires Prettier v3 (ESM-only). Prettier v2 is not supported. ↓

fix Upgrade Prettier to v3: npm install prettier@latest --save-dev

deprecated Uses of @exception, @return, @returns, @augments, @extends, @typeparam, @borrows, @constructs, @default, @external, @host, @fileoverview, @overview, @class, @const, @defaultvalue, @desc, @emits, @exception, @func, @host, @interface, @kind, @method, @prop, @returns, @see, @summary, @this, @throws, @type, @typedef, @var, @yields are deprecated in favor of standard tags. ↓

fix Use standard JSDoc tags: @param, @returns, @type, @typedef, etc.

gotcha When using multiple Prettier plugins, prettier-plugin-jsdoc must be placed at the end of the plugins list. ↓

fix Order plugins: [..., 'prettier-plugin-jsdoc']

breaking In v0.x, the plugin was CommonJS. Starting v1.0.0, it is ESM-only. ↓

fix Ensure your project uses ESM (type: "module" in package.json) or adjust Prettier configuration accordingly.

Install

npm install prettier-plugin-jsdoc

yarn add prettier-plugin-jsdoc

pnpm add prettier-plugin-jsdoc

Imports

prettier-plugin-jsdoc

wrong

import prettierPluginJsdoc from 'prettier-plugin-jsdoc'; // Not a programmatic import, it's a plugin

correct

Add to .prettierrc plugins array: "plugins": ["prettier-plugin-jsdoc"]

Plugin is loaded via Prettier configuration, not imported directly in code.

Quickstart

Installs the plugin, adds it to Prettier config, and formats a JSDoc comment from messy to clean.

// 1. Install: npm install --save-dev prettier prettier-plugin-jsdoc
// 2. .prettierrc:
{
  "plugins": ["prettier-plugin-jsdoc"]
}
// 3. Input file (example.js):
/**
 * @param {  string   }    name description
 */
function greet(name) {}
// 4. Run: npx prettier --write example.js
// Output:
/** @param {string} name Description */
function greet(name) {}