I deleted tailwind-merge from production

While auditing dependencies in my monorepo, I ran an experiment that bothered me more than it should have:

twMerge('border-grid border-red-500')
// => 'border-red-500'

border-grid is a custom utility defined in my component library's CSS. tailwind-merge has never heard of it, so it does what its heuristics say: anything shaped like border-<something> that is not a known width or style must be a border color. Two border colors conflict, the later one wins, and my utility silently vanishes from the DOM. No warning, no error... nothing. It renders fine until the day any border color class lands in the same string.

That sent me down a hole that ended with tailwind-merge gone from all seven apps in the repo, a class of bugs gone with it, and a small tool I wish I had at the start.

Why tailwind-merge exists at all

CSS does not care about the order of your class attribute. The height of class="h-9 h-8" is decided by stylesheet order, which Tailwind controls, not you. So when a Button component says h-9 and a caller passes h-8, somebody has to break the tie. tailwind-merge breaks it at runtime: parse every class string, classify every token against its tables, remove the losers. Every render. On every device. FOREVER.

To be clear, it does this well. The tables are carefully maintained, the cache makes repeat calls nearly free, and the shadcn ecosystem is built on top of it. This is not a hit piece.

But sitting with that border-grid result, the framing started to feel wrong. A class conflict is not a runtime condition. It is a line of code I wrote ONCE, in a file. The conflict is the same on every render and every device, and the resolution is the same too. Running a resolver in production to fix a static mistake is like shipping a spell checker inside a published book.

There was a second result that confirmed it:

twMerge('text-sm leading-snug text-xs')
// => 'text-xs'

The caller wanted smaller text and lost their line height. tailwind-merge treats font size as conflicting with line height, because text-sm can set both. Defensible reasoning, surprising outcome... and again, completely silent.

The plan

Resolve every conflict once, in source, and demote tailwind-merge to the job it is actually great at: checking. The same move as replacing runtime validation with a type checker. If no class string in the codebase ever needs merging, the merger can run in dev and CI and ship nowhere.

The problem is that a shadcn-style codebase is written in merge semantics on purpose. Variant systems restate properties so the merge can pick winners: the button base says border-transparent, the outline variant says border-border. Component callers pass h-8 against an h-9 base and expect to win. Turn the merge off naively and every one of those spots becomes a stylesheet-order coin flip, with no error anywhere. This is why everybody leaves it on. The off switch was always available (cva ships without merging, tailwind-variants has twMerge: false). The safety net... was not.

Step one: variants that mean what they say

I swapped tailwind-variants for a 25 line concatenation helper and made every variant string disjoint: no property set by both the base and a variant for the same modifier prefix. The contested tokens move out of the base and into every variant that does not override them. Verbose, yes. But the string now means what it says.

Proving this changed nothing was the part I cared about. Before touching anything, I captured tailwind-merge's output for all 109 variant combinations as a baseline. After the rewrite, a test asserts two things for every combination: the output matches the baseline exactly, and running twMerge over it changes nothing. The referee that was being removed is the same referee that certified the removal. That test stays in the repo permanently, because every freshly pulled shadcn component arrives written in merge semantics and fails it until the overlaps are distributed.

Step two: make the callers honest

For call sites where the override is the point, Tailwind already has a native answer: the important modifier. <Button class="rounded-full!"> beats the component's rounded-md through CSS itself, deterministically, with zero runtime. And because important and normal classes live in different buckets, a checker can stay quiet about them: the precedence is explicit.

One trap worth knowing if you try this. When a plain token gets the !, any responsive sibling on the same property needs it too. text-2xl! md:text-3xl renders 2xl at every width, because an important plain class beats a normal responsive one. The fix is text-2xl! md:text-3xl!. My first pass got this wrong on EIGHT files and the only reason I caught it is that I went looking.

I did not convert sites by hand. A script resolved each component's actual classes, diffed every class literal in all seven apps against what twMerge would drop, and rewrote the conflicting tokens. 233 call sites, each one pixel-identical, because the rewrite target is by definition the string twMerge was already producing.

Step three: flip it and keep a tripwire

With the variants disjoint and the callers explicit, cn became a plain join, and tailwind-merge moved into a dev-only tripwire that names any conflicting tokens the moment they render. Bundlers eliminate the whole branch in production.

Results, measured: roughly 25KB of minified JavaScript removed from each app's client bundle, zero visual changes across seven apps, and a permanent dev-mode alarm for the next conflict anyone writes.

And one more thing, which is my favorite part. After the migration was supposedly complete, I ran a fresh static scan over the codebase. It found two more conflicts on pages NOBODY had rendered in dev: a marketing page where py-12 was fighting p-10, and a vendored component carrying both outline-hidden and outline-none. The first one had actually become a live regression the moment the merge came off. The checker caught what the migration missed.

The tool

I extracted the pieces into a package, because the safety net is the part that did not exist. It is called overrule: https://github.com/Nic-Polumeyv/overrule

The command that earns the link here is cross. It judges every class literal twice, once with the name tables and once with your actual compiled stylesheet, and prints every place the two disagree. I pointed it back at the seven apps that started all this. One disagreement in the whole repo, and it was overrule being right: a bare filter token sitting dead next to blur-[10px], invisible to name tables because every filter utility restates the full filter chain. And the border-grid result at the top of this post? The stylesheet oracle keeps it. The compiler, unlike the tables, has actually met my utility.

The kilobytes are nice. The silent deletions were the reason.

Postscript: the CLI is Rust now

The checker grew up after this post was drafted. npm i -D overrule now installs a native binary. guard() and the test assertion are not part of the rewrite and never will be: they run inside YOUR bundle, so they stay JavaScript.

Honest numbers, because rewrite posts love to lie with them. On 84,300 files the node CLI takes 1.52s and single threaded Rust takes 1.15s. The merge engine dominates and the language barely matters. Then ten lines of rayon take it to 0.28s, because the scanner is embarrassingly parallel and Rust makes that safe. That is the actual argument for the rewrite, not the single thread delta.

The name tables side is tailwind-fuse, the Rust port of tailwind-merge's tables. The stylesheet side still compiles your classes with Tailwind itself, because a reimplementation that drifts from the real one is EXACTLY the bug class this tool exists to catch. tailwind-fuse demonstrated the thesis within the hour: the first cross run flagged the shadcn focus ring, wanting to delete focus-visible:ring-ring/50 sitting next to focus-visible:ring-[3px], because its tables cannot tell ring color from ring width through an arbitrary value. New tables, same disease, caught the same way. Every misread cross has caught since is encoded in a patch layer, each verdict taken from a tailwind-merge run first. So the tables stopped losing the argument, and tailwind-merge stopped executing anywhere in my apps, not even in dev: the tests ask the binary for verdicts, the dev guard judges with a conflict map generated from the compiled stylesheet, and the package ships with no tailwind-merge at all... not a dependency, not a peer. What survives is the role it earned: the reference every table verdict was checked against before it was encoded.

The same map now drives an eslint rule, overrule/eslint, so the conflict shows under your cursor before it shows in CI. Its fix is the same rewrite the CLI does: losers removed, nothing else touched. The one existing eslint rule in this space judges with name tables and cannot fix; this one judges with your stylesheet and can.

One last thing I learned so you do not have to: npm's spam filter permanently blocks new unscoped packages matching *-win32-x64. Not rate limiting... the name itself. The windows binary is published as overrule-windows-x64, which is also what git-cliff settled on after hitting the same wall.