prettier-plugin-blade

3.1.5 verified Sat Apr 25 auth: no javascript

An opinionated Prettier plugin for formatting Laravel Blade templates, currently at version 3.1.5 (stable). It requires Node.js >=18 and Prettier ^3.0, and optionally integrates with @prettier/plugin-php for embedded PHP formatting and prettier-plugin-tailwindcss for Tailwind CSS class sorting. Key differentiators include a ground-up rewrite in v3 with changed output, Blade syntax plugins for frameworks like Statamic, and extensive configuration options for directive spacing, echo spacing, component prefixes, and inline element behavior. Released frequently with bug fixes and improvements. Active development.

Common errors

error Error: Cannot find module 'prettier-plugin-blade' ↓

cause Plugin is not installed or not in node_modules

fix

Run npm install --save-dev prettier-plugin-blade

error The 'parser' option is not recognized by Prettier ↓

cause Parser string is not 'blade' or plugin not loaded

fix

Ensure plugin is in 'plugins' array and parser is 'blade'. Example: { plugins: ['prettier-plugin-blade'], parser: 'blade' }

error Error: Cannot find module '@prettier/plugin-php' ↓

cause PHP formatting is enabled but optional plugin not installed

fix

Install @prettier/plugin-php: npm install --save-dev @prettier/plugin-php, or disable PHP formatting by setting bladePhpFormatting: 'off'

error TypeError: Cannot read properties of undefined (reading 'blade') ↓

cause Outdated version of Prettier (v2) incompatible with plugin v3

fix

Upgrade Prettier to v3: npm install prettier@^3 --save-dev

Warnings

breaking Chisel v3 is a ground-up rewrite: output changes compared to v2. ↓

fix Pin to previous version (e.g., prettier-plugin-blade@^2) if you need stable output, or update your codebase to accommodate v3 formatting.

deprecated Prettier v2 is not supported; requires Prettier ^3.0.0. ↓

fix Upgrade Prettier to v3: npm install prettier@^3 --save-dev

gotcha The plugin requires Node.js >=18.0.0; older versions will fail. ↓

fix Ensure Node.js version is 18 or higher: node --version

gotcha When using PHP formatting (bladePhpFormatting: 'safe'), @prettier/plugin-php must be installed and in plugins list. ↓

fix Install @prettier/plugin-php and add to plugins array in .prettierrc.

gotcha CLI array options must be repeated per item (e.g., --blade-component-prefixes x --blade-component-prefixes flux), not comma-separated. ↓

fix Use repeated flags for array values in CLI. Use JSON array in .prettierrc for ease.

gotcha bladeDirectiveCaseMap option is a JSON object; passing it via CLI requires careful quoting. ↓

fix Set bladeDirectiveCaseMap in .prettierrc instead of CLI to avoid shell quoting issues.

Install

npm install prettier-plugin-blade

yarn add prettier-plugin-blade

pnpm add prettier-plugin-blade

Imports

plugin (in .prettierrc plugins array)
wrong
```
require('prettier-plugin-blade')
```
correct
```
module.exports = { plugins: ['prettier-plugin-blade'] }
```
This is a Prettier plugin, not imported directly in JS. Configure in .prettierrc or CLI.
parser (blade)
wrong
```
{ parser: 'blade.php' }
```
correct
```
{ parser: 'blade' }
```
The parser string is just 'blade', not the file extension.

options (in .prettierrc)

wrong

{ parser: 'blade' } inside overrides without files array

correct

module.exports = { plugins: ['prettier-plugin-blade'], overrides: [{ files: ['*.blade.php'], options: { parser: 'blade' } }] }

Override must specify files matching Blade templates, e.g. ['*.blade.php'].

Quickstart

Basic .prettierrc configuration to format Blade templates with Prettier.

module.exports = {
  plugins: ['prettier-plugin-blade'],
  overrides: [{
    files: ['*.blade.php'],
    options: { parser: 'blade', tabWidth: 4 }
  }]
};