rainbow-fmt

Every shade of style. A code formatter that formats code your way.

rainbow-fmt is a highly configurable, pluggable code formatter for HTML, CSS, SCSS, JavaScript, TypeScript, Svelte, Python, and any other language or DSL someone cares to describe.

It is deliberately the anti-Prettier / anti-Black. Those tools end style debates by removing choice. rainbow-fmt ends them by letting a team write its decisions down once — and then enforcing them consistently, for every language in the repository.

Status

Alpha (0.4.0). JSON, JSONC, CSS, Python, JavaScript, TypeScript, HTML, Svelte, TOML, YAML, SQL and Markdown can be formatted from the command line (docs/roadmap.md). See STATUS.md and CHANGELOG.md.

Quick start

pip install rainbow-fmt            # Python 3.12 or newer

rainbow-fmt format src/            # rewrite files in place
rainbow-fmt check .                # exit 1 if any file would change
rainbow-fmt diff config.json       # show the changes
rainbow-fmt options config.json    # the options for a file, and where each comes from

Every formatted file is verified before it is written: the syntax tree and the comments must be unchanged, and formatting the result again must change nothing (docs/cli.md).

Write your decisions down in rainbow.toml (or pyproject.toml [tool.rainbow], YAML, or package.json), in the project root:

preset = "rainbow:balanced"        # start from a preset (optional)

[core]
max_width = 100
indent_size = 2

[language.json]
object_wrap = "always"             # "preserve" | "fit" | "always"
align_values = true

[[override]]
files = ["legacy/**"]
core.indent_size = 4

.editorconfig is read too. All options and the resolution order are in docs/configuration.md.

How it compares

Black and Prettier end style discussions by allowing none. rainbow-fmt makes every decision an option, so a team's own style guide becomes a configuration file rather than a list of things to live with. Three decisions from this repository's STYLEGUIDE.md, each with the option that produces it (the full mapping):

A list of dicts hugs its brackets — Black puts each dict on a line of its own; the guide wants the brackets shared:

# Black                                      # rainbow-fmt, bracket_hug = true
rows = [                                     rows = [{
    {"property": value, "second": other},        "property": value,
    {"property": value, "second": other},        "second": other,
]                                            }, {
                                                 "property": value,
                                                 "second": other,
                                             }]

Semicolons only where the guide wants them — Prettier puts one after every statement; the guide omits them, except after a return that is not the last statement of its block:

// Prettier                                  // rainbow-fmt, semicolons = "as_needed",
function setValue(v) {                       //   return_semicolons = "unless_last"
  if (v === value) return v;                 function setValue(v) {
  value = v;                                     if (v === value) return v;
  return value;                                  value = v
}                                                return value
                                             }

Docstrings under the first letter — Black re-indents a docstring's lines to its opening quotes and keeps one-line docstrings on one line; the guide aligns continuation lines under the summary and closes on a line of its own:

# Black                                      # rainbow-fmt, docstrings = "aligned"
def region(slots, index):                    def region(slots, index):
    """Add the region after ``off``."""          """Add the region after ``off``.
                                                 """
def plan(slots):
    """Pieces covering the slots.            def plan(slots):
                                                 """Pieces covering the slots.
    One per slot, unless a region
    joins several.                                  One per slot, unless a region
    """                                             joins several.
                                                 """

Other things the two tools decide for you that are options here: the indentation (core.indent_size, 4 by default), where blank lines go inside a function (statement_blank_lines), whether a one-line object stays on one line (object_wrap), <br> or <br /> (void_elements), one selector per line or all on one (selector_list). What is written is never changed where the option says so: strings, numbers, quotes and parentheses are printed as written by every pack.

Speed. The same files, checked from the command line (docs/benchmark.md has the method and the numbers):

Formatting alone is on a par with Black and about twice Prettier's time per file; verification (a re-parse and a second formatting pass, which neither of the others does) doubles it. Repeated runs are fast: files a previous run found formatted are skipped from a cache, and many files are formatted in parallel.

Documentation

Development

Requires Python 3.12 or newer.

python -m venv .venv
source .venv/bin/activate          # Windows: .venv\Scripts\activate
pip install -e '.[dev]'

pytest                             # tests + coverage report
ruff check . && ruff format --check .
mypy                               # strict; configured in pyproject.toml

The same checks, plus a package build and a benchmark (python -m rainbow_fmt.benchmark, docs/benchmark.md), run in GitLab CI on every push and merge request (.gitlab-ci.yml). Pushing a tag vX.Y.Z that matches __version__ publishes the package to PyPI (docs/releasing.md).

New features are developed tests-first: the tests describing the intended API are written and reviewed before the implementation. Architectural decisions are recorded in docs/adr/.

License

MIT — see LICENSE.

Project tracking

TODO.md (high-level tasks), TASKS.md (detailed next tasks), STATUS.md (current state).