@aforemendude/prettier-plugin-wrap-comments weekly downloads statistics

@aforemendude/prettier-plugin-wrap-comments

A Prettier plugin that wraps non-JSDoc JavaScript and TypeScript comments as Markdown. It uses each comment marker's real column to calculate the available content width, so nested comments wrap more narrowly than top-level comments.

Requirements

• Node.js 20 or newer to use the plugin • Node.js 22.12 or newer to develop the plugin • Prettier 3 (>=3.9.0 <4.0.0)

Install

Use

Add the plugin to your Prettier config:

Then run Prettier normally:

Use With prettier-plugin-jsdoc

When using both plugins, @aforemendude/prettier-plugin-wrap-comments must be loaded after prettier-plugin-jsdoc:

This order is required regardless of prettier-plugin-jsdoc's documentation saying that it should be the last plugin. With wrap-comments last, ordinary comments are handled here and parsing is delegated to the preceding JSDoc plugin, so JSDoc comments are formatted as well.

Cache Repeated CLI Runs

Prettier's CLI cache skips files that have not changed since a successful formatting pass. Enable it in package scripts so contributors use it consistently. This repository uses the faster metadata strategy for local formatting:

The first cached run still processes every file; later runs skip files whose relevant metadata and other cache keys have not changed. Omit --cache-strategy metadata to use the default content strategy when workflows such as Git operations frequently change timestamps without changing file contents.

By default, Prettier stores the cache under node_modules/.cache/prettier/, which is normally excluded from version control with node_modules. Prettier does not include plugin versions or implementations in its cache keys, so run the uncached command once after updating this plugin or another Prettier plugin. Running Prettier without --cache, as the format:nocache script does, also removes the default cache. See [Prettier's CLI cache documentation][prettier-cache] for cache keys, strategies, and custom cache locations.

Behavior

The plugin wraps comments for Prettier's babel, babel-ts, and typescript parsers. It runs during parser preprocessing: the nearest preceding plugin for the selected parser, or Prettier's built-in parser when there is none, preprocesses and parses the source first. This plugin rewrites eligible comments from that parsed comment list, and Prettier then formats the rewritten source with its built-in JavaScript and TypeScript printers. If the parser cannot parse the preprocessed source, the plugin leaves the source unchanged.

Offset-sensitive formatting is conservative. Full-file formatWithCursor calls skip comment rewriting so Prettier can map the cursor from the original source. During range formatting, preprocessing does not rewrite text outside Prettier's selected range; eligible comments inside that range can still be wrapped.

Comment text is normalized and reflowed with Prettier's Markdown parser. The available content width is based on Prettier's printWidth minus the column where the comment text starts. tabWidth, useTabs, and endOfLine are used when measuring and rebuilding comments. When tabWidth is 0, tabs contribute zero columns during measurement, as they do in Prettier. If the plugin must synthesize indentation at a positive column, it uses spaces because zero-width tabs cannot advance to that column.

Standalone // comments are wrapped in place. Adjacent standalone line comments are combined and reflowed as one Markdown block when they are directly next to each other and their // markers start in the same column.

Trailing // comments stay in place when the full source line fits within printWidth. If the source line is too long, the comment is moved above the code and normally wrapped using the code line's indentation. On a line made up of closing delimiters such as }, ], or ), the moved comment is indented one additional level so it remains visually inside the construct being closed. When a comment directly trails the root value of a JSX expression or template interpolation, it can move above that value and wrap inside the expression delimiters. Nested or otherwise ambiguous expression comments and comments in JSX spreads stay in place.

Non-JSDoc /* ... */ comments are also normalized as Markdown. A block comment may stay on one line if the normalized comment fits within printWidth; otherwise, only standalone block comments are expanded into star-prefixed blocks. Long inline block comments are left unchanged when they cannot fit on one line.

Multiline block comments are normalized as conventional block-comment text before Markdown parsing: leading indentation is removed, and a * that is the first non-whitespace character on a body line is treated as comment formatting, not Markdown content. This also applies to unstarred /* ... */ blocks, so use line comments when Markdown-significant indentation or leading * characters must be preserved exactly.

JSX and TSX expression comments use the expression contents, not the outer React expression braces, to decide whether a block comment is standalone, leading, trailing, or inline. A comment-only expression like {/* ... */} can wrap as a standalone JSX comment. A leading expression comment like {/* ... */ label} can move above label and wrap. A trailing expression comment like {label /* ... */} can move before label and wrap. A true inline expression comment like {"abc" + /* ... */ "123"} is left unchanged when it cannot fit on one line.

prettier-ignore markers are preserved and affect wrapping only when the marker body is exactly prettier-ignore. When one of these markers is directly above a standalone block comment, the plugin leaves that block comment unchanged. If the block comment is one the plugin would otherwise wrap, the following code still formats normally; if the block comment is already skipped by the plugin, such as a JSDoc or directive block, Prettier keeps its normal ignore behavior for the following code.…

Description from the npm listing.