Documentation
Playground

whitehall lint

Catch errors, bugs, and style issues before building.

Usage

whitehall lint [options]

Basic Linting

Check all .wh files in your project:

whitehall lint

Output shows issues by category:

error[E001]: Missing key prop in animated list
  → src/routes/+screen.wh:12:5
   |
12 |     <Card animate:flip>
   |     ^^^^^^^^^^^^^^^^^^
   |
   = note: Add key={item.id} to track items

warning[W042]: Unused variable 'count'
  → src/components/Counter.wh:3:5

✖ 1 error, 1 warning found

Options

Auto-fix

Automatically fix issues where possible:

whitehall lint --fix

Safe fixes are applied automatically:

  • Add missing keys
  • Remove unused imports
  • Fix deprecated syntax
  • Reorder props (also done by formatter)

Select Categories

Check only specific rule categories:

whitehall lint --select=correctness,style
whitehall lint --select=performance

Ignore Rules

Skip specific rules:

whitehall lint --ignore=W042,W043

Specific Files

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

Rule Categories

Whitehall includes 102 rules across 18 categories:

Correctness (E001-E020)

Critical errors that will cause runtime failures:

  • Missing keys in animated lists
  • Invalid crossfade keys
  • Missing required props
  • Type mismatches

Props (E021-E030)

Component prop issues:

  • Unknown props
  • Conflicting props
  • Invalid prop values

Style (W001-W020)

Code style and consistency:

  • Prefer shorthand syntax
  • Use transition: for symmetric animations
  • Simplify expressions

Crossfade (W021-W030)

Shared element transition best practices:

  • Matching keys across screens
  • Consistent types
  • Performance optimization

Routing (E031-E040)

Navigation and routing errors:

  • Invalid route paths
  • Missing route parameters
  • Loader/screen mismatches

Navigation (W031-W040)

Navigation warnings:

  • Hardcoded route strings
  • Missing navigation state types

State (W041-W050)

State management issues:

  • Unused variables
  • State mutations in render
  • Missing state initialization

Animation (W051-W060)

Animation best practices:

  • Missing durations
  • Conflicting transitions
  • Performance-heavy animations

Data (E041-E050)

Data loading and serialization:

  • Missing type annotations for $import
  • Non-serializable data classes
  • Invalid JSON

Layout (W061-W070)

Layout and composition:

  • Deeply nested components
  • Missing accessibility props
  • Inefficient layouts

Component (W071-W080)

Component design:

  • Too many props
  • Complex components (split suggested)
  • Missing prop documentation

Performance (W081-W090)

Performance optimizations:

  • Heavy computations in render
  • Missing keys in lists
  • Unnecessary recomposition triggers

Icons (E051-E055)

Icon usage errors:

  • Unknown icon names
  • Invalid icon sets

FFI (E056-E060)

Foreign function interface:

  • Invalid FFI signatures
  • Type mapping errors
  • Missing FFI decorators

Dependencies (W091-W095)

Dependency management:

  • Unused dependencies
  • Version conflicts
  • Deprecated packages

Morph (W096-W100)

Progress-driven morphing:

  • Invalid driver configurations
  • Conflicting morph properties
  • Missing anchor points

Widgets (E061-E065)

Home screen widgets:

  • Unsupported components in widgets
  • Invalid widget sizes
  • Missing widget configuration

Notifications (E066-E070)

Notification channels:

  • Invalid priorities
  • Missing notification props

Example Output

$ whitehall lint

src/routes/+screen.wh
  error[E001]: Missing key prop in animated list
   → line 23
   = Add key={item.id} to track items during reordering

  warning[W042]: Unused variable 'isLoading'
   → line 8
   = Remove or use this variable

src/components/UserCard.wh
  warning[W072]: Component has 12 props, consider splitting
   → line 1
   = Components with many props are hard to maintain

✖ 1 error, 2 warnings found in 2 files

CI Integration

GitHub Actions

name: Lint

on: [push, pull_request]

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Install Whitehall
        run: cargo install whitehall

      - name: Lint
        run: whitehall lint

Pre-commit Hook

# .git/hooks/pre-commit
#!/bin/bash

whitehall lint
if [ $? -ne 0 ]; then
  echo "Linting failed. Fix errors before committing."
  exit 1
fi

Configuration

Customize rules in whitehall.toml:

[lint]
# Ignore specific rules
ignore = ["W042", "W072"]

# Select only certain categories
select = ["correctness", "performance"]

# Error on warnings
strict = true

Inline Suppressions

Disable rules for specific lines:

// whitehall-ignore-next-line W042
var unused = 0

// whitehall-ignore W042,W043
var alsoUnused = 1

Common Issues

Missing Keys

Error:

error[E001]: Missing key prop in animated list

Fix:

<Card key={item.id} animate:flip>
  <Text>{item.name}</Text>
</Card>

Invalid Crossfade

Error:

error[E002]: Crossfade key must match across screens

Ensure both screens use the same key format:

// List
<Image transition:crossfade="poster-{movie.id}" />

// Detail
<Image transition:crossfade="poster-{$route.params.id}" />

Unused Variables

Warning:

warning[W042]: Unused variable 'count'

Fix by using or removing:

// Remove if unused
// var count = 0

// Or use it
var count = 0
<Text>{count}</Text>

Best Practices

  • Run linter before committing
  • Fix errors immediately (don't ignore)
  • Use --fix for safe auto-fixes
  • Address warnings to improve code quality
  • Enable strict mode in CI

Run whitehall lint before whitehall build to catch errors early. Some lint errors will cause build failures anyway.

See Also