formatter-development

Formatter Development

Use crates/biome_formatter/CONTRIBUTING.md and the language formatter's guide as the canonical architecture references. Inspect neighboring node implementations before selecting IR primitives.

Workflow

1. Reproduce the behavior with a focused internal formatter spec or quick_test.
2. Inspect the node fields, comments, and nearby formatting rules.
3. Implement the smallest layout change using formatter IR.
4. Run focused formatter tests and inspect snapshots.
5. Compare with Prettier when compatibility is relevant.
6. Format and lint before committing.

Node Rules

Generated node rules implement FormatNodeRule. In fmt_fields:

• destructure the generated *Fields type explicitly;
• format source tokens through their typed accessors;
• use _ for an intentionally ignored field rather than ..;
• preserve every token and comment unless the formatter contract intentionally replaces it;
• keep layout decisions near the type that owns them.

format_verbatim_* methods preserve a node's source text. Replace verbatim formatting with structured formatting only when tests cover valid, malformed, and commented forms of the node.

Token Rules

Format, replace, or remove every token. Formatter tests panic when a token is not handled, preventing accidental source loss.

Use format_replaced when substituting a token and format_removed when removing one.

Ad-Hoc Formatting

Format a node through node.format() when possible. Its regular rule checks formatter-suppression comments as part of normal formatting.

When a helper formats a node or its tokens outside FormatNodeRule, run the formatter tests. If the suppression-check assertion reports a node, call f.context().comments().mark_suppression_checked(node.syntax()) for that reported node. The assertion shows that the helper bypasses the node's normal suppression check.

IR Composition

Use semantic IR rather than writing whitespace as arbitrary text:

• space() for required spaces;
• soft line breaks for optional wrapping;
• hard line breaks for mandatory breaks;
• groups to choose flat versus expanded layout;
• indentation primitives matching the enclosing construct;
• conditional content tied to the group whose fit decision controls it.