Clarity Formatter

The Clarity formatter automatically shapes your smart contract code to follow standardized style rules. Consistent formatting improves readability and makes collaboration easier across teams.

Formatting philosophy

The formatter applies an opinionated standard designed to make Clarity code more readable:

• Line length – wraps lines at 80 characters by default
• Indentation – uses two spaces for consistency
• Structure – enforces consistent patterns for functions, let bindings, and control flow

You can customize these defaults to match your preferences.

Integration points

1

Clarity VS Code Extension

Format directly in the editor.

2

Clarinet CLI

Format via command line, including entire projects.

Comparison table

Aspect	Manual formatting	Clarity formatter
Consistency	Varies by developer	Uniform across the codebase
Speed	Time-consuming	Instant
Error-prone	Yes	No
Team coordination	Requires a style guide	Automatic enforcement

Best practices

• Format on save – enable automatic formatting in VS Code
• Pre-commit hooks – ensure code is formatted before commits
• Team adoption – share consistent settings with your team

Formatting rules in detail

Function definitions

Functions span multiple lines with consistent indentation:

(define-public (my-func
    (amount uint)
    (sender principal)
  )
  (ok true)
)

Single arguments can remain on the first line:

(define-read-only (get-balance (who principal))
  (ok u0)
)

Let expressions

Bindings are placed on separate lines with consistent indentation:

(let (
  (a u1)
  (b u2)
)
  (body-expression)
)

Control flow (if, match)

Each branch receives its own line:

(if condition
  (then-expression)
  (else-expression)
)

(match optional-value
  value (handle-some value)
  (handle-none)
)

Tuples and maps

The formatter automatically converts to sugared syntax with proper formatting:

;; Input: (tuple (n1 u1) (n2 u2))
;; Output:
{
  n1: u1,
  n2: u2,
}

Usage examples

VS Code integration

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

CLI usage

clarinet format --in-place

Format with custom settings:

clarinet format -i 4 -l 120 --in-place

Check formatting in CI/CD pipelines:

clarinet format --check

The --check flag validates that all Clarity files are properly formatted without changing them, which is ideal for continuous integration workflows.

Ignoring blocks of code

Prevent formatting for specific code blocks:

;; @format-ignore
(define-constant something (list
  1     2  3  ;; Preserves custom spacing
  4 5 ))