whitehall format

Automatically format Whitehall code with zero configuration.

Usage

whitehall format [options]

Basic Formatting

Format all .wh files in your project:

whitehall format

This formats files in-place, automatically fixing:

• Indentation (2 spaces)
• Line width (100 characters)
• Prop ordering
• Spacing around operators
• Trailing commas

Options

Check Mode (CI)

Verify formatting without modifying files:

whitehall format --check

Exit codes:

• 0 - All files formatted correctly
• 1 - Some files need formatting

Perfect for CI/CD pipelines:

# GitHub Actions
- name: Check formatting
  run: whitehall format --check

Show Diff

Preview changes without applying:

whitehall format --diff

Format Specific Files

whitehall format src/routes/+screen.wh
whitehall format src/components/*.wh

Formatting Rules

Indentation

2 spaces (not configurable):

<Column>
  <Text>Hello</Text>
</Column>

Line Width

100 characters (not configurable):

<TextField
  bind:value={email}
  label="Email Address"
  helperText="We'll never share your email"
/>

Prop Ordering

Props are automatically ordered by category:

1. Binding (bind:value, bind:checked)
2. Transitions (in:, out:, animate:)
3. Core props (text, label)
4. Styling (color, fontSize)
5. Spacing (p, m, gap)
6. Layout (fillMaxWidth, weight)
7. Events (onClick)
8. Other

Before:

<Button onClick={save} text="Save" color="primary" fillMaxWidth />

After:

<Button text="Save" color="primary" fillMaxWidth onClick={save} />

Multi-line Props

When a component exceeds line width, props are wrapped:

<Button
  text="Save Changes"
  background="primary"
  fillMaxWidth
  onClick={handleSave}
/>

Spacing

Consistent spacing around operators and braces:

// Before
val x=5+3
<Text>{count+1}</Text>

// After
val x = 5 + 3
<Text>{count + 1}</Text>

Trailing Commas

Added automatically in multi-line contexts:

val items = [
  "Apple",
  "Banana",
  "Cherry",
]

Editor Integration

VS Code

Format on save with the Whitehall extension:

// .vscode/settings.json
{
  "[whitehall]": {
    "editor.formatOnSave": true
  }
}

Vim/Neovim

autocmd BufWritePre *.wh !whitehall format %

Pre-commit Hook

Auto-format before commits:

# .git/hooks/pre-commit
#!/bin/bash
whitehall format
git add -u

Philosophy

Whitehall's formatter is intentionally opinionated and zero-config:

• No configuration files
• No customizable rules
• One canonical style
• Eliminates bike-shedding

Before and After Examples

Complex Component

Before:

<TextField bind:value={email} type="email" label="Email Address" helperText="We'll send updates here" error={!isEmailValid} onClick={handleFocus} fillMaxWidth px={16} />

After:

<TextField
  bind:value={email}
  type="email"
  label="Email Address"
  helperText="We'll send updates here"
  error={!isEmailValid}
  px={16}
  fillMaxWidth
  onClick={handleFocus}
/>

Control Flow

Before:

@if(isLoading){<CircularProgressIndicator/>}else{
<LazyColumn>@for(item in items){<Text>{item}</Text>}</LazyColumn>}

After:

@if (isLoading) {
  <CircularProgressIndicator />
} else {
  <LazyColumn>
    @for (item in items) {
      <Text>{item}</Text>
    }
  </LazyColumn>
}

Nested Components

Before:

<Column><Row gap={8}><Icon name="star"/><Text>4.5</Text></Row><Text fontSize={24}>Product Name</Text></Column>

After:

<Column>
  <Row gap={8}>
    <Icon name="star" />
    <Text>4.5</Text>
  </Row>
  <Text fontSize={24}>Product Name</Text>
</Column>

Performance

The formatter is fast:

• ~1000 files/second
• Parallel processing by default
• In-place updates (no temporary files)

Comparison with Other Formatters

Feature	Whitehall	Prettier	Black
Configuration	None	Optional	Minimal
Customizable	No	Yes	Limited
Speed	Very Fast	Fast	Fast
Philosophy	Opinionated	Opinionated	Opinionated

Troubleshooting

Format Changes Not Applied

Ensure you're not using --check mode:

whitehall format  # Applies changes
whitehall format --check  # Only checks

Unexpected Formatting

The formatter follows strict rules. If output seems wrong, it's likely following the canonical style.

File Not Formatted

Ensure the file has .wh extension and valid syntax:

whitehall lint src/routes/+screen.wh

See Also

• whitehall lint - Catch errors and style issues
• whitehall build - Build after formatting