Styler

Styler is an Elixir formatter plugin that's combination of mix format and mix credo, except instead of telling you what's wrong, it just rewrites the code for you to fit its style rules.

You can learn more about the history, purpose and implementation of Styler from our talk: Styler: Elixir Style-Guide Enforcer @ GigCity Elixir 2023

Features

auto-fixes many credo rules, meaning you can turn them off to speed credo up
keeps a strict module layout
alphabetizes module directives
extracts repeated aliases
pipes and unpipes function calls based on the number of calls
optimizes standard library calls (a |> Enum.map(m) |> Enum.into(Map.new) => Map.new(a, m))
replaces strings with sigils when the string has many escaped quotes
... and so much more

See our Rewrites documentation on hexdocs for all the nitty-gritty on what all Styler does

Who is Styler for?

Styler was designed for a large team (40+ engineers) working in a single codebase. It helps remove fiddly code review comments and removes failed linter CI slowdowns, helping teams get things done faster. Teams in similar situations might appreciate Styler.

Its automations are also extremely valuable for taming legacy elixir codebases or just refactoring in general. Some of its rewrites have inspired code actions in elixir language servers.

Conversely, Styler probably isn't a good match for:

libraries
experimental, macro-heavy codebases
small teams that don't want to think about code standards

Installation

Add :styler as a dependency to your project's mix.exs:

def deps do
  [
    {:styler, "~> 1.0.0-rc.1", only: [:dev, :test], runtime: false},
  ]
end

Then add Styler as a plugin to your .formatter.exs file

[
  plugins: [Styler]
]

And that's it! Now when you run mix format you'll also get the benefits of Styler's Stylish Stylings.

Speed: Expect the first run to take some time as Styler rewrites violations of styles and bottlenecks on disk I/O. Subsequent formats formats won't take noticeably more time.

Configuration

Styler can be configured in your .formatter.exs file

[
  plugins: [Styler],
  styler: [
    alias_lifting_exclude: [...]
  ]
]

Styler's only current configuration option is :alias_lifting_exclude, which accepts a list of atoms to not lift. See the Module Directive documentation for more.

No Credo-Style Enable/Disable

Styler will not add configuration for ad-hoc enabling/disabling of rewrites. Sorry! Its implementation simply does not support that approach. There are however many forks out there that have attempted this; please explore the Github forks tab to see if there's a project that suits your needs or that you can draw inspiration from.

Ultimately Styler is @adobe's internal tool that we're happy to share with the world. We're delighted if you like it as is, and just as excited if it's a starting point for you to make something even better for yourself.

Thanks & Inspiration

Sourceror

Styler's first incarnation was as one-off scripts to rewrite an internal codebase to allow Credo rules to be turned on.

These rewrites were entirely powered by the terrific Sourceror library.

While Styler no longer relies on Sourceror, we're grateful for its author's help with those scripts, the inspiration Sourceror provided in showing us what was possible, and the changes to the Elixir AST APIs that it drove.

Styler's AST-Zipper implementation in this project was forked from Sourceror. Zipper has been a crucial part of our ability to ergonomically zip around (heh) Elixir AST.

Credo

We never would've bothered trying to rewrite our codebase if we didn't have Credo rules we wanted to apply.

Credo's tests and implementations were referenced for implementing Styles that took the work the rest of the way.

Thanks to Credo & the Elixir community at large for coalescing around many of these Elixir style credos.

remoteoss/elixir-styler