It delegates to the tailwindcss CLI’s new canonicalize subcommand — the same engine that powers the Prettier plugin. So you get sorting, normalization, and duplicate collapsing powered directly by the Tailwind CSS engine.
It hooks into mix format via Phoenix LiveView 1.1’s attribute_formatters API and works with LSP format-on-save (tested with Expert).
Setup is two lines — one dep, one formatter config:
If you’re already using the :tailwind hex package, it detects your binary and profile automatically. Make sure your tailwind version in config/config.exs is at least 4.2.2 and run mix tailwind.install after changing it.
Requires Elixir ~> 1.18, Phoenix LiveView ~> 1.1, and tailwindcss CLI >= 4.2.2 (the first version with canonicalize). The canonicalize --stream flag that makes this possible was merged in tailwindcss#19796.
It was a long time coming. I first opened a PR for Phoenix LiveView asking the team to make HTMLFormatter.tokenize/1 public. José Valim came back with a better idea — attribute_formatters (phoenix_live_view#3781) — which gave formatters a proper hook into the template pipeline.
The initial implementation parsed Tailwind’s output CSS to derive the sort order. It worked, but I was never happy with it, especially with format-on-save enabled in an editor. The ideal solution was to hand the formatting off to Tailwind itself, and that became possible once the canonicalize subcommand landed. I contributed a --stream flag (tailwindcss#19796) so the CLI could stay alive as a long-running process, and after that the library was the easy part.
Best part about it for me is you stop thinking about class order — write whatever, hit save, done. On a team it’s even better because diffs stay clean and everyone’s output looks the same.
Thanks! Interestingly, Tailwind’s canonicalize subcommand already resolves conflicts within a single class string — if you give it bg-blue-500 px-4 bg-red-500, it’ll collapse that down to bg-red-500 px-4. Last one wins.
The tricky part is that the interesting merge case is runtime — something like class={["bg-blue-500 px-4", @class]} where one side is dynamic. A formatter can’t resolve that since it doesn’t know the value of @class at format time. And doing it at runtime would mean either shipping and running the Tailwind binary in prod, or reimplementing its conflict resolution in pure Elixir — both non-trivial.
Unsure whether this is canonical_tailwind or Tailwind’s canonicalize subcommand, but I just added canonical_tailwind to our (quite large) project and ran into a couple of issues:
We had one instance where classes were wrapped in a ~s’’’ heredoc, and the parser crashed (failing to find the closing '’’).
There were many instances where the formatter swapped class strings between nearby but different HTML elements.
There were several instances where multi-line class strings were truncated (the formatter dropped continuation lines) - these in classes such as:
<div class={[
“class …”,
“class …”,
…
]}>
[edit]
That last one may have been in classes such as
<div class="class class class
class class class">
that is, where a linebreak breaks the class string.
Thanks for trying this out on a large project and sharing what you ran into!
All three are symptoms of the same bug — newlines in class strings broke the line-based protocol with the tailwindcss CLI. Multi-line strings got truncated, and subsequent attributes received stale responses (which looked like classes swapping between elements). The heredoc crash was a related issue where trailing newlines got stripped, producing invalid Elixir.
Fixed in v0.1.1. One thing to note: multi-line class strings are now collapsed into a single line, since tailwindcss canonicalize always returns a single line. If you prefer breaking long class lists across lines, you can use a list instead:
Thanks for the quick fix - the new version is certainly much better! I’m not seeing any of the same issues with mix format, however a couple of things I notice:
The formatter collapses multi-line class strings into a single, very long line. We tend to wrap very long classes over multiple lines for readability, but although mix format no longer crashes and does canonicalize, it collapses these multiple-line strings into a single line every time. This is probably a difficult one to solve - understandably the lines have to be joined in order to canonicalize, so wrapping and formatting them in the same way afterwards is tricky. We can certainly standardize on multiple strings in an array.
Formatting via ElixirLS (format-on-save) is still failing on ~s''' delimited class strings with Unable to format: token missing on lib/myapp_web/live/components/thing.ex:8:2: error: missing terminator: ‘’’ (for heredoc starting at line 5), even though mix format works.
On the multi-line collapsing, that’s inherent to how canonicalize works. The classes have to be joined into a single string for the CLI, and there’s no way to know where the original line breaks were meaningful. Using a list of strings is probably the cleanest workaround.
On the ~s''' issue with ElixirLS, I’d need more detail to dig into that one. Could you file an issue on GitHub?
Just shipped 0.1.5. The headline: if format-on-save just wasn’t working for you under Expert or ElixirLS, 0.1.5 fixes it.
Also tightened pool reliability: workers that go missing now recover (long-running LSP sessions used to break after a crash), cold start is serialized to avoid mixed-config workers, and config drift after pool start raises a loud error instead of silently using stale config (a small breaking change for umbrella setups that depended on the old quiet behavior).
And if you haven’t tried canonical_tailwind yet, this is a good moment. The canonicalizer in tailwindcss has gotten noticeably smarter over the past few releases: combining text-* with leading-*, collapsing matching width/height into size-*, modernizing calc(var(--spacing)*…) into --spacing(…), and now in v4.3.0, migrating [&:has(…)] to has-[…] and preserving significant whitespace and original units in arbitrary values. canonical_tailwind delegates to the user’s installed binary, so all of that lands for you the moment you bump :tailwind.
It used to run a pool of tailwindcss CLI processes to parallelize mix format. But that pool only ever helped a full-tree format. Since Elixir 1.17, mix format caches unchanged files, so even that only runs over the whole tree on the first format or a fresh CI checkout. Everything else (format-on-save, a single file, a repeat mix format after edits) touches a handful of files, which one warm CLI handles fine. 0.2.0 drops the pool for that single warm CLI, so those everyday cases start sooner. The one tradeoff is the first full-tree format, which gives up the old parallelism.
It’s also lighter: a long editor session now holds one CLI instead of up to six, so a few hundred MB instead of well over a gigabyte.
And the single CLI is now keyed per resolved configuration, so one mix format can span apps or directories that resolve to different configs: an umbrella with per-app tailwind profiles, or a project using subdirectories with per-directory .formatter.exs files. Each config gets its own warm CLI.
If you’re upgrading: :pool_size is deprecated and ignored, and the config-drift error from 0.1.5 is gone, so the per-app workaround for mismatched umbrella configs is no longer needed.
canonical_tailwind already canonicalizes class attributes in HEEx. But Tailwind classes often live in plain .ex code too: helper functions, module attributes, class-builder lists. A formatter can’t safely touch those on its own, since it can’t tell a Tailwind class string from any other string.
~TW lets you mark a string as a class list, so mix format canonicalizes it:
