{"id":13491097,"url":"https://github.com/adobe/elixir-styler","last_synced_at":"2025-05-14T01:07:40.098Z","repository":{"id":149210033,"uuid":"621411440","full_name":"adobe/elixir-styler","owner":"adobe","description":"An @elixir-lang code-style enforcer that will just FIFY instead of complaining","archived":false,"fork":false,"pushed_at":"2024-04-11T17:58:01.000Z","size":355,"stargazers_count":583,"open_issues_count":7,"forks_count":21,"subscribers_count":15,"default_branch":"main","last_synced_at":"2024-04-14T13:33:03.679Z","etag":null,"topics":["elixir","formatter","styler"],"latest_commit_sha":null,"homepage":"","language":"Elixir","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/adobe.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2023-03-30T15:54:25.000Z","updated_at":"2024-04-17T17:03:15.891Z","dependencies_parsed_at":"2023-10-03T00:04:25.357Z","dependency_job_id":"bc5aa6d7-b5ec-4a62-8513-9c774472f1aa","html_url":"https://github.com/adobe/elixir-styler","commit_stats":null,"previous_names":[],"tags_count":69,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adobe%2Felixir-styler","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adobe%2Felixir-styler/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adobe%2Felixir-styler/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adobe%2Felixir-styler/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/adobe","download_url":"https://codeload.github.com/adobe/elixir-styler/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248389085,"owners_count":21095516,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["elixir","formatter","styler"],"created_at":"2024-07-31T19:00:53.519Z","updated_at":"2025-04-11T11:49:18.285Z","avatar_url":"https://github.com/adobe.png","language":"Elixir","funding_links":[],"categories":["Elixir"],"sub_categories":[],"readme":"[![Hex.pm](https://img.shields.io/hexpm/v/styler)](https://hex.pm/packages/styler)\n[![Hexdocs.pm](https://img.shields.io/badge/docs-hexdocs.pm-purple)](https://hexdocs.pm/styler)\n[![Github.com](https://github.com/adobe/elixir-styler/actions/workflows/ci.yml/badge.svg)](https://github.com/adobe/elixir-styler/actions)\n\n# Styler\n\nStyler is an Elixir formatter plugin that's combination of `mix format` and `mix credo`, except instead of telling\nyou what's wrong, it just rewrites the code for you to fit its style rules.\n\nYou can learn more about the history, purpose and implementation of Styler from our talk: [Styler: Elixir Style-Guide Enforcer @ GigCity Elixir 2023](https://www.youtube.com/watch?v=6pF8Hl5EuD4)\n\n## Features\n\nStyler fixes a plethora of elixir style and optimization issues automatically as part of mix format.\n\n[See Styler's documentation on Hex](https://hexdocs.pm/styler/styles.html) for the comprehensive list of its features.\n\nThe fastest way to see what all it can do you for you is to just try it out in your codebase... but here's a list of a few features to help you decide if you're interested in Styler:\n\n- sorts and organizes `import`/`alias`/`require` and other [module directives](docs/module_directives.md)\n- keeps lists, sigils, and even arbitrary code sorted with the `# styler:sort` [comment directive](docs/comment_directives.md)\n- automatically creates aliases for repeatedly referenced modules names ([_\"alias lifting\"_](docs/module_directives.md#alias-lifting))\n- optimizes pipe chains for [readability and performance](docs/pipes.md)\n- rewrites strings as sigils when it results in fewer escapes\n- auto-fixes [many credo rules](docs/credo.md), meaning you can spend less time fighting with CI\n\n## Who is Styler for?\n\nStyler 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.\n\nIts 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.\n\nConversely, Styler probably _isn't_ a good match for:\n\n- experimental, macro-heavy codebases\n- teams that don't care about code standards\n\n## Installation\n\nAdd `:styler` as a dependency to your project's `mix.exs`:\n\n```elixir\ndef deps do\n  [\n    {:styler, \"~\u003e 1.4\", only: [:dev, :test], runtime: false},\n  ]\nend\n```\n\nThen add `Styler` as a plugin to your `.formatter.exs` file\n\n```elixir\n[\n  plugins: [Styler]\n]\n```\n\nAnd that's it! Now when you run `mix format` you'll also get the benefits of Styler's Stylish Stylings.\n\n**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.\n\n### Configuration\n\nStyler can be configured in your `.formatter.exs` file\n\n```elixir\n[\n  plugins: [Styler],\n  styler: [\n    alias_lifting_exclude: [...]\n  ]\n]\n```\n\nStyler's only current configuration option is `:alias_lifting_exclude`, which accepts a list of atoms to _not_ lift. See the [Module Directive documentation](docs/module_directives.md#alias-lifting) for more.\n\n#### No Credo-Style Enable/Disable\n\nStyler [will not add configuration](https://github.com/adobe/elixir-styler/pull/127#issuecomment-1912242143) for ad-hoc enabling/disabling of rewrites. Sorry!\n\nHowever, Smartrent has a fork of Styler named [Quokka](https://github.com/smartrent/quokka) that allows for finegrained control of Styler. Maybe it's what you're looking for. If not, you can always fork it or Styler as a starting point for your own tool!\n\nUltimately 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.\n\n## WARNING: Styler can change the behaviour of your program!\n\nIn some cases, this can introduce bugs. It goes without saying, but look over your changes before committing to main :)\n\nA simple example of a way Styler changes the behaviour of code is the following rewrite:\n\n```elixir\n# Before: this case statement...\ncase foo do\n  true -\u003e :ok\n  false -\u003e :error\nend\n\n# After: ... is rewritten by Styler to be an if statement!.\nif foo do\n  :ok\nelse\n  :error\nend\n```\n\nThese programs are not semantically equivalent. The former would raise if `foo` returned any value other than `true` or `false`, while the latter blissfully completes.\n\nHowever, Styler is about _style_, and the `if` statement is (in our opinion) of much better style. If the exception behaviour was intentional on the code author's part, they should have written the program like this:\n\n```elixir\ncase foo do\n  true -\u003e :ok\n  false -\u003e :error\n  other -\u003e raise \"expected `true` or `false`, got: #{inspect other}\"\nend\n```\n\nAlso good style! But Styler assumes that most of the time people just meant the `if` equivalent of the code, and so makes that change. If issues like this bother you, Styler probably isn't the tool you're looking for.\n\nOther ways Styler can change your program:\n\n- [`with` statement rewrites](https://github.com/adobe/elixir-styler/issues/186)\n- [config file sorting](https://hexdocs.pm/styler/mix_configs.html#this-can-break-your-program)\n- and likely other ways. stay safe out there!\n\n## Thanks \u0026 Inspiration\n\n### [Sourceror](https://github.com/doorgan/sourceror/)\n\nStyler's first incarnation was as one-off scripts to rewrite an internal codebase to allow Credo rules to be turned on.\n\nThese rewrites were entirely powered by the terrific `Sourceror` library.\n\nWhile `Styler` no longer relies on `Sourceror`, we're grateful for its author's help with those scripts, the inspiration\nSourceror provided in showing us what was possible, and the changes to the Elixir AST APIs that it drove.\n\nStyler's [AST-Zipper](`m:Styler.Zipper`) implementation in this project was forked from Sourceror. Zipper has been a crucial\npart of our ability to ergonomically zip around (heh) Elixir AST.\n\n### [Credo](https://github.com/rrrene/credo/)\n\nWe never would've bothered trying to rewrite our codebase if we didn't have Credo rules we wanted to apply.\n\nCredo's tests and implementations were referenced for implementing Styles that took the work the rest of the way.\n\nThanks to Credo \u0026 the Elixir community at large for coalescing around many of these Elixir style credos.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fadobe%2Felixir-styler","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fadobe%2Felixir-styler","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fadobe%2Felixir-styler/lists"}