@poliklot/prettier-plugin-handlebars weekly downloads statistics

@poliklot/prettier-plugin-handlebars

Prettier plugin for classic Handlebars templates with mixed HTML markup.

It formats .hbs / .handlebars files used in HTML-heavy Handlebars projects, with a focus on stable, idempotent output and preserving classic Handlebars semantics.

Install

Quick Start

Recommended config:

The explicit override keeps .hbs files on this plugin even in Prettier versions that also know about other Handlebars-like parsers.

Configuration Patterns

1. Minimal plugin setup

Use this only when you have verified that your Prettier version and editor resolve .hbs files to this plugin. The explicit override below is safer for shared projects.

2. Explicit Handlebars override

Use this when you want stable format-on-save behavior in editors, or when your project mixes multiple template types.

3. Explicit Handlebars override with project style

Normal Prettier options still work and often matter a lot for .hbs.

4. Local plugin path during dogfooding

Useful when you are testing the plugin from a neighboring repository before publishing a new npm version.

5. JSON config

CLI

Published package:

Local plugin build:

Project Setup Audit

The package also ships a small setup helper:

By default this is a dry run. It reports whether the project has:

• local prettier and @poliklot/prettier-plugin-handlebars dependencies; • a Prettier config that loads the plugin; • an explicit *.hbs / *.handlebars override with parser: "handlebars"; • .prettierignore patterns that skip Handlebars files.

Apply supported JSON config changes with:

Use it in CI or local checks with:

The helper can create or update .prettierrc, .prettierrc.json, and the prettier object in package.json. JavaScript, JSON5, YAML, and TOML configs are detected but not rewritten automatically; the command prints the manual action instead.

API

Plugin Options

dataAttributeOrder

Custom ordering override for data-* attributes.

| Default | CLI Override | API Override |

| [] | --data-attribute-order | dataAttributeOrder: string[] |

maxEmptyLines

Maximum number of consecutive blank lines preserved between nodes.

| Default | CLI Override | API Override |

| 1 | --max-empty-lines | maxEmptyLines: number |

classAttributeSameLine

Keep the first and last tokens of multiline conditional class attributes glued to their surrounding quotes.

| Default | CLI Override | API Override |

| false | --class-attribute-same-line | classAttributeSameLine: boolean |

classAttributeLayout

Control whether class attribute values may use multiple physical lines. The default auto mode preserves the existing formatting rules. Use single-line to keep static and conditional class values on one line; the surrounding HTML tag may still wrap.

| Default | CLI Override | API Override |

| "auto" | --class-attribute-layout | classAttributeLayout: "auto" \| "single-line" |

classAttributeLayout: "single-line" takes precedence over classAttributeSameLine, whose existing behavior remains unchanged.

What The Plugin Handles Today

• HTML elements, void elements, comments, and custom elements • {{mustache}}, {{{triple-stash}}}, block helpers, {{else}}, {{else if ...}}, partials • whitespace control markers such as {{~ value ~}} and {{~/if~}} • raw blocks such as {{{{raw}}}}...{{{{/raw}}}} • block partials such as {{#> layout}}...{{/layout}} • inline partial definitions such as {{#*inline "name"}}...{{/inline}} • Mustache inheritance with parent templates and block overrides, such as {{', and ' [more-paths...] - run an idempotence / crash-safety sweep over real template corpora • npm run corpus:oss - clone and check a public OSS corpus from Ghost themes, Ghost classic templates, WET, express-hbs, pillarjs/hbs, and other real .hbs projects • npm run fuzz:parser - run deterministic malformed-template fuzzing against the built plugin • npm run format:hbs-tree -- - format every .hbs / .handlebars file under a temp project copy before running that project's own build • PRETTIER_VERSION=3.2 npm run smoke:install - pack the plugin, install it into a clean temp project, format a sample, and verify that handlebars is not installed • npm run pack:check - inspect npm package contents with npm pack --dry-run

VS Code Companion

If you work with Handlebars in VS Code, try HBS Master as a companion extension. It pairs well with this formatter and makes day-to-day .hbs editing more comfortable.

For formatter setup details, see Editor Setup.

Troubleshooting and Migration

• Troubleshooting • Editor Setup • Migration Notes • Changelog • Release Automation

Notes

• This README is intentionally self-contained so it works well on npm too. • If your editor does not format .hbs on save, the safest setup is an explicit overrides rule with parser: "handlebars".

Shared embedding work

See shared embedding architecture and cross-repository dependencies. This source work depends on the core tracking issue.

Description from the npm listing.