0022. One formatting style for page files; the script block is kept as written
- Status: Accepted (provisional)
- Date: 2026-11-14
- Decided by: integrator (internal only)
- Planning item: none; WP2 formatter
Context
duolith fmt needs one canonical layout for page files so agents and people stop arguing about whitespace, and so diffs stay small. It must be idempotent and must never change what a page means. The page has three languages in it: our markup, TypeScript in the script block and in {expressions}, and CSS in <style>.
The obvious way to format the TypeScript is oxc. oxc 0.158 (our pinned version) ships a code generator, not a formatter. We tried oxc_codegen on the social example's script: it drops every blank line between statements, drops trailing // comments, re-indents with tabs, and splits small object literals over many lines. That is a printer for compiled output, not a formatter for code people read. lightningcss is not yet a dependency.
Decision
- Script block: kept exactly as written, apart from blank lines at its start and end. Once oxc's formatter is published and preserves comments and blank lines, the script block will go through it (a new decision).
- Expressions and attribute values: printed exactly as written, including multi-line arrow functions.
- Markup: two-space indentation, one child per line. An element whose children are only text and expressions stays on one line when that line fits in 100 columns; words of long text fill lines up to 100 columns.
- Opening tags: on one line while they fit in 100 columns; otherwise one attribute per line, with
>or/>on its own line. Text values use double quotes unless they contain one. - Whitespace that matters is kept: text that touches an element or expression with no space between them stays touching, because a line break there would render as a space.
- Comments stay where they were, as written. One blank line is kept where the source had one or more. A top-level
<style>block always has a blank line before it. - Style blocks: re-indented one level inside
<style>, otherwise as written, until lightningcss arrives. - A page with syntax errors is not formatted;
duolith fmtreports the errors and leaves the file alone. - The formatter is generic over the syntax tree: new elements and attributes need no formatter change.
Alternatives considered
| Option | Why not |
|---|---|
Format the script with oxc_codegen | Loses blank lines and trailing comments; output reads like compiled code |
| Shell out to Prettier for TypeScript | Adds Node to the compiler's path and a second source of style rules |
| Prettier-style text filling with whitespace sensitivity settings | Options contradict "one style, no options"; our touching rule covers the cases that matter |
Consequences
Formatting a page never touches its TypeScript, so a messy script stays messy until oxc's formatter lands. The tests in crates/fmt/tests/formatting.rs hold the formatter to its promises: every example and fixture parses to the same tree before and after formatting, formatting twice changes nothing, and comments survive. A future syntax change that adds a new node kind to duolith_syntax::Node needs one new match arm in crates/fmt/src/items.rs.