HBS Neat (Handlebars Neat)

HBS Neat is a high-performance formatter specifically engineered for complex HTML files containing Handlebars syntax. It provides both a VS Code Extension for real-time coding and a Powerful CLI for automated workflows.

✨ Professional CLI Support

You can enforce consistent formatting across your entire project or CI/CD pipeline.

Usage in `package.json`

"scripts": {
  "format:hbs": "hbs-neat \"src/**/*.html\"",
  "format:check": "hbs-neat \"src/**/*.html\" --check"
}

CLI Options

Flag	Description
`[patterns]`	Glob patterns to format (default: `*/.html`).
`-d, --dry-run`	Show which files would be modified without changing them.
`-c, --check`	Check if files are formatted. Exits with code 1 if issues are found (Perfect for CI).
`-i, --ignore`	Patterns to ignore (default: `node_modules/`, `dist/`).

🚀 Why HBS Neat?

Most formatters treat {{ ... }} as invalid HTML, leading to broken attributes or collapsed blocks. HBS Neat acts as a smart middleware that shields your logic before delegating to Prettier.

Key Features

📐 Intelligent Block Line-Breaking: Keeps {{#if}}, {{#each}}, and Partials on their own lines.
🛡️ Smart Quote Escaping: Automatically handles nested quotes within attributes (e.g., data="Text \"inside\" text").
🔗 Context-Aware Indentation: Captured HTML context ensures blocks align perfectly with their parent elements.
⚡ Single-Line Normalization: Shrinks messy multi-line partials into clean, scannable lines.
🎨 Prettier Integrated: Automatically respects your .prettierrc or project configurations.

🛠 VS Code Usage

Format on Demand

Use the standard VS Code shortcut:

Windows/Linux: Shift + Alt + F
macOS: Shift + Option + F

Format on Save

Add this to your .vscode/settings.json:

{
  "editor.formatOnSave": true,
  "[html]": { "editor.defaultFormatter": "buiquockhai.hbs-neat" },
  "[handlebars]": { "editor.defaultFormatter": "buiquockhai.hbs-neat" }
}

⚙️ Configuration

Setting	Type	Default	Description
`hbsFormatter.printWidth`	`number`	`120`	Line length limit before wrapping.
`hbsFormatter.tabWidth`	`number`	`2`	Number of spaces per indentation level.
`hbsFormatter.useTabs`	`boolean`	`false`	Indent lines with tabs instead of spaces.

🧩 How it works

HBS Neat follows a strict 3-stage pipeline:

Extraction: Tokens are mapped to placeholders; block tags are shielded in <pre> tags.
Sanitization: Internal attributes are audited, and quotes are escaped to prevent Prettier crashes.
Restoration: Formatted HTML is scanned, and placeholders are swapped back with sanitized HBS code.

📝 License

Distributed under the MIT License.

Developed with ❤️ by Bui Quoc Khai

HBS Neat

Khai Bui