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

npm i -D prettier-plugin-blade-conventions

{
  "plugins": ["prettier-plugin-blade-conventions"]
}

prettier --write "resources/views/**/*.blade.php"

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

{
  "overrides": [
    {
      "files": ["*.blade.php"],
      "options": {
        "bladeAttributeHead": ["id", "name", "type", "wire:key", "wire:*", "x-init", "x-data", "x-*"],
        "bladeAttributeTail": ["data-*", "aria-*", "role"]
      }
    }
  ]
}

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:

>= 4 attributes    multiline
   3 attributes    multiline unless the line is under bladeCompactWidth
<= 2 attributes    multiline only past printWidth
>= 3 attributes    body on its own line, either way

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.

<x-form.checkbox id="topic-music" label="Music" inline />

<x-form.radio
    id="plan-free"
    name="plan"
    value="free"
>
    Free
</x-form.radio>

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:

<button
    style="
        height: 30px;
        width: 30px;
    "
    type="button"
>

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 <script>, <style>, <pre> or <textarea> are left alone, since there the lines are the content.

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

<x-layouts:app>

    <livewire:thing />

</x-layouts:app>

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 <script>, <style>, <pre> or <textarea> 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.

<input aria-describedby="email-help" class="form-input" data-lpignore="true" id="email" wire:model="email" required />

<input
    id="email"
    class="form-input"
    wire:model="email"
    data-lpignore="true"
    aria-describedby="email-help"
    required
/>

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.…