Download the PHP package joelstein/blade-formatter without Composer

Blade Formatter

A tool that formats Blade templates and Livewire Single File Components. Like Laravel Pint for Blade — run a single command and your files are clean. Includes a VS Code extension with format-on-save and automatic PHP/Blade language switching.

What It Does

Blade Formatter runs three formatters in sequence:

1. PHP formatting — Formats PHP in Livewire SFC sections and @php/@endphp blocks using Laravel Pint
2. Blade indentation — Auto-indents Blade templates with proper nesting for directives, HTML, components, and Alpine.js attributes
3. Tailwind class sorting — Sorts Tailwind CSS classes using Prettier with prettier-plugin-tailwindcss

Each formatter can be enabled or disabled independently. Markdown mail templates are never indented, since Markdown renders an indented line as a code block.

Why Not Prettier?

Blade Formatter only changes leading whitespace. It re-indents, but doesn't reflow. Line breaks are left as written.

Other tools, including pint --blade, run Blade through Prettier, which also joins short lines, wraps at a print width, and moves attributes onto their own lines. That works well for plenty of projects. A few reasons Blade Formatter doesn't:

• HTML whitespace can be meaningful in ways JSX whitespace usually isn't, so rewrapping sometimes changes what renders.
• Blade mixes PHP and HTML, and how a template reads best tends to depend on what it's doing more than on a fixed width.
• Line length and attributes-per-line are things developers reasonably disagree about.
• Blade components are often one deeply nested tree, since there's no easy way to define and reuse smaller components within a single file. A tall component is fine, since it folds in the editor, but wrapping compounds at every level of nesting.

Mostly this is preference. If you'd rather have full reflow, pint --blade does it well.

Skipped Files

Some Blade files are never formatted, because reformatting them would change what they do rather than just how they look:

These are skipped even when named explicitly on the command line.

Mail templates are a partial case: only indentation is skipped. Pint and Tailwind sorting still run, since neither changes the whitespace Markdown reads.

Opting Out

Wrap a region in blade-formatter-disable / blade-formatter-enable comments to leave it byte-for-byte unchanged. Everything outside the region is still formatted:

Omit the closing comment to opt out the rest of the file. Put one at the top and the whole file is skipped.

Class attribute order never affects CSS, so Tailwind sorting is normally safe everywhere, including inside @verbatim where Vue and Handlebars templates genuinely want it. The exception is markup that is itself the content: documentation pages showing code samples, or fixtures asserted against as strings. Sorting rewrites the example you are demonstrating, even when it is HTML-escaped inside <pre>.

Requirements

• PHP 8.2+
• Node.js (for Tailwind class sorting)

Installation

The VS Code extension requires the Laravel extension.

Usage

Configuration

Create a blade-formatter.json in your project root:

exclude takes a path substring or a delimited regex, matched relative to the working directory, and applies to every run mode — including --diff, --dirty, and paths named on the command line. flux/icon, vendor/mail, and vendor/notifications are always excluded.

VS Code Extension

The extension provides format-on-save and automatic PHP/Blade language switching in Livewire SFCs. All settings are under bladeFormatter.*:

Formatting options (indent size, enable/disable formatters, etc.) are configured in blade-formatter.json — not in VS Code settings. This keeps CLI and editor output consistent.

Note: If you use the Laravel Pint VS Code extension with Laravel.pint.runOnSave enabled, Pint will strip use statements from SFCs that are only referenced in Blade — undoing the blade formatter's work. Disable Pint's run-on-save for Blade files in your .vscode/settings.json:

CI Integration

License

MIT