@1adybug/prettier-plugin-block-padding weekly downloads statistics

@1adybug/prettier-plugin-block-padding

Notice: This project is implemented entirely by AI coding tools.

中文文档

A Prettier plugin that inserts blank lines between selected statements and class members. It wraps Prettier's estree printer to control statement containers and separators, while leaving expression and object-property formatting to Prettier.

Key Features

The following describes the default behavior. The configuration options control rules, scope, and blank-line count.

• All Code Blocks Grouping: Inserts an additional blank line before and after specific statements in file top-level, function bodies, if/for/while statement blocks, TypeScript namespaces, and class static initialization blocks (i.e., two line breaks separating adjacent statements), enhancing structural separation. Switch-case sequences remain delegated to Prettier because they are not block statements. • 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. • Class Member Separation: Pads multiline class members and separates adjacent properties and methods, including single-line methods. • Single-line Detection: Single-line blocks and expressions do not trigger additional blank lines, except for type declarations, object/array literals, and the property/method separation rule. • Parser Compatibility: Provides adapters for babel, babel-ts, and typescript, delegating to preceding compatible parsers or the official parser. Padding remains in the estree printing stage.

Behavior Details

With the default configuration, statement containers (Program, BlockStatement, TSModuleBlock, and StaticBlock) and class bodies (ClassBody) receive a blank line between adjacent statements or members in the following cases. See Configuration to select rules and spacing:

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, TSModuleDeclaration, etc.), an additional blank line is added between it and adjacent statements. • Class Declarations: The separate classes rule pads multiline class declarations by default; blockPaddingClassMode: "always" also includes single-line and empty classes. • Multi-line Expression Blocks: 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: ... • 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. • Padding Between Statements and Class Members: The plugin controls container braces and statement/member separators; expression and object-property formatting remains delegated to Prettier. Function bodies and other nested statement containers receive the same padding rules. • Single-line Exceptions: Type declarations, object/array literals, and adjacent class properties/methods can trigger padding even when printed on one line.

Adjacent statements are separated by a line break. Matching boundaries receive one additional line break by default, creating one blank line.

Examples

Basic Example (Top-level)

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

Function Body Example

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

Multi-line Expression Block Example

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

Single-line Does Not Trigger Blank Lines

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

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

Installation

Usage

Create prettier.config.mjs (in a custom combination, place this plugin after other estree printers):

Compatibility

• Prettier: ^3.8.0 (Prettier 3.8 or later within 3.x) • Parsers: babel, babel-ts, typescript • Module: ESM

Configuration

All options are available in JavaScript/JSON configurations and as native Prettier CLI options. Defaults preserve the existing formatting behavior.

| Option | Default | Values and behavior |

| blockPaddingRules | All nine rules below | An array of enabled rules; [] disables padding and delegates printing and comment handling to Prettier | | blockPaddingScope | "all" | "all" for supported containers; "top-level" for the file's Program only | | blockPaddingMode | "around" | "around" requires either neighboring statement to match; "between" requires both | | blockPaddingLines | 1 | A positive safe integer specifying actual blank lines at matching boundaries | | blockPaddingClassMode | "multiline" | "multiline" uses the existing forced-break detection; "always" includes single-line and empty class declarations |

Rule Names

| Rule | Matches |…

Description from the npm listing.