prettier-plugin-block-padding

prettier-plugin-block-padding

中文文档

Important Notice: This project is entirely generated by Cursor + Claude 4.5 Sonnet Thinking

A Prettier plugin that intelligently inserts blank lines between specific statements to enhance visual grouping of modules and semantic blocks, without altering Prettier's original style and line-breaking decisions. The plugin works on "statement sequences" based on Prettier 3's estree printer, supports all code blocks (including function bodies, if/for/while statement blocks), and does not rewrite formatting and indentation inside expressions.

Key Features

• All Code Blocks Grouping: Inserts an additional blank line before and after specific statements in all code blocks, including file top-level, function bodies, if/for/while statement blocks (i.e., two line breaks separating adjacent statements), enhancing structural separation.
• Smart Multi-line Expression Block Recognition: Automatically identifies and adds blank lines around multi-line expression blocks such as template literals, function expressions, class expressions, JSX elements, etc., improving code readability.
• TypeScript Namespace Support: Applies the same rules to member statements inside namespace/module (TSModuleBlock), ensuring correct line breaks between braces and first/last lines.
• Smart Single-line Detection: Single-line objects, functions, template literals, etc., do not trigger additional blank lines (except object/array literals), avoiding excessive separation.
• Collaboration with Official Parsers: Reuses official babel, babel-ts, and typescript parsers, only overriding the "statement concatenation" during the estree printing stage, leaving other formatting to Prettier.

Behavior Details

In "all code blocks (BlockStatement)", including file top-level (Program), function bodies, if/for/while statement blocks, and TypeScript namespace blocks (TSModuleBlock), the plugin adds an additional blank line between adjacent statements in the following cases:

Unconditional Blank Lines (Even for Single Lines)

• TypeScript Type Declarations: interface, type, enum (including those wrapped with export)
• Top-level Object/Array Literals:
  • Variable declarations initialized with object/array literals
  • Expression statements with literals as the main body

Blank Lines Only for Multi-line Cases

• Multi-line Block Statements: When a statement's printed result is multi-line (e.g., if, for, while, do/while, try/catch/finally, switch, function, class, TSModuleDeclaration, etc.), an additional blank line is added between it and adjacent statements.

• Multi-line Expression Blocks (New): When the following expressions span multiple lines, an additional blank line is added between them and adjacent statements:

  • Template literals: `...`
  • Tagged templates: styled`...`
  • Arrow function expressions: () => {}
  • Function expressions: function() {}
  • Class expressions: class {}
  • Multi-line function calls: fn(...)
  • Multi-line new expressions: new Class(...)
  • JSX elements: <div>...</div>
  • JSX fragments: <>...</>

Strict Constraints

• No Blank Lines Outside Container Boundaries: Will not add extra blank lines before the file's first line or after the file's last line. However, if the file's first or last line's statement matches the above rules (e.g., object literals, type declarations, multi-line block statements), it will still add blank lines between it and adjacent statements.
• Only Blank Lines Between Statements: Never rewrites formatting within a single statement; specific layouts of expressions, object properties, and function bodies are still determined by Prettier.
• Single-line Does Not Trigger Blank Lines: When a block/expression is finally printed as a single line (without line breaks), it does not trigger additional whitespace.

Summary: The plugin always ensures "at least one line break between adjacent statements", and when rules are matched, an additional line break is added to form a visual blank line.

Examples

Basic Example (Top-level)

Object/array literals, TS type declarations, and multi-line block statements trigger additional whitespace:

const a = 1

const b = {
    name: "Tom",
    age: 18,
}

if (a) {
    const d = 1
}

interface User {
    name: string
}

const c = [1, 2, 3]

Function Body Example

The plugin also works inside function bodies, if/for/while, and all code blocks:

function foo() {
    const a = 1

    const b = {
        name: "Tom",
        age: 18,
    }

    if (a) {
        const x = 1

        const y = {
            name: "Jerry",
            age: 20,
        }
    }

    const c = [1, 2, 3]
}

Multi-line Expression Block Example

Template literals, function expressions, etc., spanning multiple lines also add blank lines:

const a = 1

const template = `
    hello, world!
    this is a multiline template
`

const fn = () => {
    console.log("test")
}

const b = 2

const styled = css`
    color: red;
    font-size: 14px;
`

const c = 3

Single-line Does Not Trigger Blank Lines

Single-line template literals, function expressions, etc., do not add blank lines:

const singleTemplate = `hello`
const singleFn = () => console.log("test")
const d = 4

Note: Single-line object/array literals still add blank lines (unconditional rule):

const a = 1

const singleObj = { a: 1 }

const b = 2

Installation

npm i -D prettier-plugin-block-padding

Usage

Add the plugin to your Prettier configuration (recommended to place at the end of the plugins array to ensure the custom estree printer takes effect):

{
    "plugins": ["other-plugins", "prettier-plugin-block-padding"]
}

Compatibility

• Prettier: v3 and above (loaded as a plugin)
• Parsers: babel, babel-ts, typescript
• Module: ESM

⚠️ Important Notice

There are serious compatibility issues with the "@ianvs/prettier-plugin-sort-imports" plugin. Please do not use them together!

Scope and Limitations

• Inserts additional blank lines "between statements" in all code blocks (including file top-level, function bodies, if/for/while statement blocks, TS namespace blocks).
• Supported expression block types: template literals, tagged templates (e.g., styled-components), arrow functions, function expressions, class expressions, multi-line function calls, new expressions, JSX elements, and fragments.
• Does not rewrite formatting inside expressions or object properties, and does not affect comment positions or line-breaking decisions (handled by Prettier).
• Will not arbitrarily add extra blank lines at the beginning/end of files/blocks.
• Single-line expressions (except object/array literals) do not trigger blank lines, avoiding excessive separation.

Quick Local Testing

npx prettier --plugin prettier-plugin-block-padding --parser typescript --write "src/**/*.{ts,tsx,js,jsx}"

Or use the project script (if exists):

npm run test:quick

If you encounter blank line behavior inconsistent with expectations at boundary conditions or specific syntax, feel free to submit a minimal reproducible example for improvement.