prettier-plugin-blade-conventions weekly downloads statistics

prettier-plugin-blade-conventions

Opinionated Blade layout, layered on prettier-plugin-blade.

Prettier reasons about width alone. This adds attribute ordering, attribute-count thresholds, and respect for the line breaks you wrote yourself.

Install

Options

Declared Prettier options, so they go in your Prettier config, alongside those of prettier-plugin-blade.

| Option | Default | Effect |

| bladeCompactWidth | 90 | Width under which a borderline tag still fits on one line | | bladeExpandFrom | 3 | Attribute count from which a tag is treated as heavy | | bladeAttributeHead | [] | Attribute names always printed first, in list order | | bladeAttributeTail | [] | Attribute names always printed last, in list order | | bladePreserveElements | [] | Tags whose content must not be touched at all |

Prettier's own printWidth and tabWidth apply as usual, and every option of prettier-plugin-blade stays available.

Three of its defaults are changed here, both overridable:

• bladeInlineIntentElements drops p, which otherwise keeps a long paragraph on a single line whatever printWidth says. • bladeDirectiveArgSpacing is none. PSR-12 spaces a control keyword from its condition and leaves a call tight, so @foreach ($a as $b) but @include('partials.head'). The upstream override list already holds exactly the directives named after a PHP statement, and is left alone. • bladePhpFormatting is off. Echoes and @php blocks are out of reach anyway, but directive arguments are not, and safe rewrites them as soon as @prettier/plugin-php is installed.

Layout

With the defaults:

The three counts follow bladeExpandFrom, so setting it to 2 shifts them to 3 / 2 / 1. Widths include the indent and are measured on the opening tag alone.

Spreading something out is always honoured: a tag or a body you broke across lines stays that way, whatever its width. Keeping something on one line is honoured within limits — it holds while the line fits bladeCompactWidth and the tag carries fewer than bladeExpandFrom attributes, past which the thresholds win. Two identical tags each keep their own form.

An attribute value you spread over several lines stays spread, whatever its width:

Prettier flattens such a value as soon as the result fits, and flattens a class even when the tag stays open. Same asymmetry as everywhere else here: nothing is spread for you, and nothing you spread is closed back up. Width never enters into it, so a value you wrote on one line stays there however long it grows. Values inside a , , or are left alone, since there the lines are the content.

A blank line you opened or closed a body with is kept:

Prettier reads both as leading and trailing whitespace of the body and drops them; a blank line between two siblings it already keeps. A run of several collapses to one, and blank lines inside a , , or are left where they are. Nothing is restored after the fact: a blank line an earlier run removed is gone, the rule only keeps the ones still in the file.

Attribute order

Attributes form three blocks, in this order: valued, boolean, then any bare {{ $attributes }} bag. The first two are sorted the same way, the bag keeps its relative order.

bladeAttributeHead names come first in list order, bladeAttributeTail names last in list order, everything else alphabetically in between. Alphabetical is the baseline: with no lists at all, everything is still sorted that way.

A pattern is a literal name or a glob, where * stands for any run of characters, empty included, anywhere in the pattern: data-*, *-class and my-*-class all work. Everything else is read literally, so the dot in wire:model.live is a dot.

A name matching several patterns takes the one pinning the most characters, then the one with fewer wildcards, then the one listed first. So a literal beats a glob covering it, data-test-* beats data-*, and my-*-class beats *-class. That decides which entry a name belongs to; where that entry sits is your list order, and names sharing an entry break ties alphabetically.

A leading : or @ is ignored on both sides, so class covers class, :class and @class([...]) alike. Only the leading one — wire:key still matches on its own.

A tag whose attributes hold a Blade comment is left untouched.

textarea, pre and the other elements whose content is read verbatim keep their body glued to the brackets. Their attributes still get ordered and spread; only the content is left alone, since indenting it would change the value of the field.

Escape hatches

bladePreserveElements: ["x-code"] does the same permanently, for a component whose content is whitespace-significant — one wrapping a , typically. Prettier cannot know that on its own and will collapse the content.

A @word starting a text run is read as a directive. Escape it as @@word.

Limits

A tag carrying a Blade control directive as an attribute is left untouched entirely, neither reordered nor relaid out. That is the price of never lifting an attribute out of its branch.

A tag opened in one directive branch and closed in another may comes out with broken indentation. Wrap the two unbalanced blocks in {{-- prettier-ignore-start --}} / {{-- prettier-ignore-end --}}; what sits between them still gets formatted.

Some constructs are deliberately left out of the analysis rather than reformatted on a guess: @php blocks and the heredocs inside them, {{ }} and {!! !!} echoes, and any tag the rules cannot take apart with certainty. Skipping them costs formatting, never correctness.

Nothing here changes the rendered DOM. A file whose formatting would is reported and left untouched.

Description from the npm listing.