Herb Formatter experimental preview

Package: @herb-tools/formatter

Experimental Preview

This formatter is currently in experimental preview. While it works for many common cases, it may potentially corrupt files in edge cases. Only use on files that can be restored via git or other version control systems.

---

Auto-formatter for HTML+ERB templates with intelligent indentation, line wrapping, and ERB-aware pretty-printing.

Perfect for format-on-save in editors and formatting verification in CI/CD pipelines. Transforms templates into consistently formatted, readable code while preserving all functionality.

Installation

Global Installation

npm

npm install -g @herb-tools/formatter

pnpm

pnpm add -g @herb-tools/formatter

yarn

yarn global add @herb-tools/formatter

bun

bun add -g @herb-tools/formatter

One-time Usage

For occasional use without installing:

npx @herb-tools/formatter template.html.erb

Preview Releases

Want to try unreleased features? Use pkg.pr.new to run the formatter from any commit or PR:

npx https://pkg.pr.new/@herb-tools/formatter@{commit} template.html.erb

Replace {commit} with a commit SHA (e.g., 0d2eabe) or branch name (e.g., main). Find available previews at pkg.pr.new/~/marcoroth/herb.

Project Installation

npm

npm add -D @herb-tools/formatter

pnpm

pnpm add -D @herb-tools/formatter

yarn

yarn add -D @herb-tools/formatter

bun

bun add -D @herb-tools/formatter

After installing as a dev dependency, initialize the configuration:

npm

npx herb-format --init

pnpm

pnpm herb-format --init

yarn

yarn herb-format --init

bun

bunx herb-format --init

Then add format scripts to your package.json:

package.json

{
  "scripts": {
    "herb:format": "herb-format",
    "herb:format:check": "herb-format --check"
  }
}

Then run the scripts:

npm

npm run herb:format
npm run herb:format:check

pnpm

pnpm herb:format
pnpm herb:format:check

yarn

yarn herb:format
yarn herb:format:check

bun

bun run herb:format
bun run herb:format:check

Usage

Command Line

Basic usage:

herb-format
herb-format template.html.erb
herb-format templates/

Initialize configuration:

# Create a .herb.yml configuration file
herb-format --init

Options

Check Mode:

# Check if files are formatted without modifying them
herb-format --check template.html.erb

# Check all files in current directory
herb-format --check

Input Sources:

# Format specific file
herb-format templates/index.html.erb

# Format all .html.erb files in directory
herb-format templates/

# Format all .html.erb files in current directory (default)
herb-format

# Format from stdin
cat template.html.erb | herb-format

Help and Version:

# Show help
herb-format --help

# Show version information
herb-format --version

Configuration

Create a .herb.yml file in your project root to configure the formatter:

herb-format --init

Basic Configuration

.herb.yml

formatter:
  enabled: true  # Must be enabled for formatting to work
  indentWidth: 2
  maxLineLength: 80

  # Additional glob patterns to include (additive to defaults)
  include:
    - '**/*.xml.erb'

  # Glob patterns to exclude from formatting
  exclude:
    - 'vendor/**/*'
    - 'node_modules/**/*'
    - 'app/views/generated/**/*'

Default File Patterns

By default, the formatter processes:

• **/*.html
• **/*.rhtml
• **/*.html.erb
• **/*.html+*.erb
• **/*.turbo_stream.erb

The include patterns are additive - they add to the defaults.

Configuration Options

• enabled: true or false - Must be true to enable formatting
• indentWidth: Number (default: 2) - Spaces per indentation level
• maxLineLength: Number (default: 80) - Maximum line length before wrapping
• include: Array of glob patterns - Additional patterns to format (additive to defaults)
• exclude: Array of glob patterns - Patterns to exclude from formatting

Force Flag

Format files even when formatter is disabled:

# Force formatting when disabled in config
herb-format --force

# Force formatting on an excluded file
herb-format --force app/views/excluded-file.html.erb

When using --force on an excluded file, the formatter will show a warning but proceed with formatting.

Disabling Formatting for Entire Files v0.8.2+

You can disable formatting for an entire file by adding the ignore directive anywhere in your template:

<%# herb:formatter ignore %>

Example:

ignored.html.erb

<%# herb:formatter ignore %>

<div><div>This entire file will not be formatted</div></div>

formatted.html.erb

<div>
  <div>This file will be formatted</div>
</div>

Important

The <%# herb:formatter ignore %> directive must be an exact match. Extra text or spacing will prevent it from working.

Rewriters

The formatter supports rewriters that allow you to transform templates before and after formatting.

Configure rewriters in your .herb.yml:

.herb.yml

formatter:
  enabled: true
  indentWidth: 2

  rewriter:
    # Pre-format rewriters (run before formatting)
    pre:
      - tailwind-class-sorter

    # Post-format rewriters (run after formatting)
    post: []

Built-in Rewriters

• tailwind-class-sorter - Automatically sorts Tailwind CSS classes according to the recommended order

Custom Rewriters

You can create custom rewriters by placing them in .herb/rewriters/ and referencing them in your config.

For detailed documentation on creating and using rewriters, see the Rewriter Documentation.