Why the package exists and the choices that fix its API. ARCHITECTURE.md is the source of truth
for the internal shape — the compiled plan, the selection cache, which shapes are load-bearing;
README.md documents the API. Each decision below still holds; a decision that stops holding gets
replaced here, not annotated.
A drop-in replacement, not a new API
Context. @codefast/ui styles every component with tailwind-variants. Its configuration shape — base,
variants, defaultVariants, compoundVariants, slots, compoundSlots, extend — is the right vocabulary; what
fell short was resolution cost on hot render paths and some type-inference edges. Inventing a different API would have
forced a rewrite of the consumer for no gain in expressiveness.
Decision. Keep the upstream configuration shape and the twMerge option name exactly, and resolve every
configuration to what upstream tailwind-variants resolves it to, so the migration for most codebases is the import
specifier. The exports are tv, createTV, cn, cx, VariantProps and the configuration types; where the API
departs from upstream's, the README's migration section lists every difference.
Consequences. A unit test paraphrases the README's examples, a behaviour sweep covers the upstream shapes, and
@codefast/ui moved over by changing imports. A difference in what a configuration resolves to is a bug, not a
departure. The constraint runs the other way too: an API idea that upstream users could not express is out of scope
here.
createTV returns { tv, cn }, and nothing global is mutable
Context. Upstream's createTV(options) returns a bare tv, exposes a mutable defaultConfig, and ships cnMerge.
Global mutable configuration is the one upstream shape that fights the compile-once design below: a plan compiled under
one merge config cannot be trusted after the global changes.
Decision. createTV(options) returns { tv, cn } that share the options, and there is no mutable global: no
defaultConfig, no cnMerge. Local tv(config, options) still overrides the factory, one option at a time.
Consequences. Every resolver knows its merge configuration at compile time. Migration needs one destructure where
upstream assigned createTV's result directly, and the README's migration section records it with the other departures.
Settle everything once, when a component is called again
Context. A configuration is fixed the moment tv is called; the resolver it returns runs on every render, forever.
Upstream pays for dictionary walks and array flattening on each call. But a design system defines every component at
module load and renders many of them once or not at all on a given page, so work done inside tv() is paid by
components that never earn it back.
Decision. tv() only wraps the configuration. The first calls resolve straight from it, through a cold lane that
answers exactly what the plan answers; the next call compiles the plan — precomputed slot positions, compound conditions
turned into checks, each variant value flattened to a string the first time a call selects it — and every call after is
string concatenation over that plan. A component without slots resolves its first two calls cold, because a cold flat
call costs less than a compile and many components render exactly twice; a slot component compiles on its second,
because a cold slot call costs more.
Consequences. A definition and a single render each cost less than upstream's, and a component pays for its plan
only once it has rendered more than that. The benchmark suite prices both ends (define-only-*, first-render-*,
two-renders-* and three-renders-* against the resolution rows) so the trade stays visible. The cold lane is a second
implementation of the resolution rules and is held to the plan by the behaviour sweep, which drives every case through a
fresh resolver as well as a shared one. Anything that would move work back into the per-render path is a regression,
whatever it saves at definition or first render.
Cache resolutions per selection, with an opt-out
Context. A list renders the same few variant selections thousands of times, and both the plan walk and the merge are pure functions of the selection.
Decision. A resolver remembers what each selection resolved to, in a bounded store keyed by the selection. From the
second call on, slot components return the same object of slot functions for the same selection.
cacheResolutions: false disables the store for a component whose values are unique per call.
Consequences. Repeated selections cost a lookup. Two things callers must know, and the README says both: the returned slot object is shared, so it must not be mutated; and a variant fed ids or timestamps should opt out or it fills the store with entries nothing reads again.
The merge engine is cn, and the application may replace it
Context. Conflict resolution is what makes className overrides safe, and every first render, every unseen
className and every cold page load runs it on strings no cache has seen. cn produces the same output as
tailwind-merge — this repository's own class strings agree across both — and merges such a string faster, for a
somewhat larger bundle. A variant library that builds an engine from a configuration at runtime still makes every
application ship the compiler.
Decision. cn >= 0.5 is a peer dependency. The package imports its twMerge as the default merge and re-exports
its cn, whose own argument cache answers a repeated call before any join. The twMerge option takes true, false,
or a merge function; custom class groups are an extendTailwindMerge result from cn/config the caller builds and
passes in. There is no twMergeConfig, because accepting a configuration means importing the code that compiles one
into every bundle that never uses it.
Consequences. One engine per application: an app that still imports tailwind-merge aliases it to cn. A merge
function passed in replaces the engine only where it is passed: in that resolver, or, given to createTV, in its tv
and in the cn it returns, which then keeps a memo of its own over that merge; the exported cn stays the engine's.
The merge runs on a selection a resolver has not answered yet and on a caller's class it has not remembered, so the
engine sets the cost of a first render and of a className unique to its call. Callers who turn merging off own their
conflicts.
Types describe what the selection can be, no more
Context. Variant props are the public contract a component's own props extend, so a wrong inference is a wrong component API.
Decision. VariantProps<typeof resolver> derives the selection type from the configuration, boolean variants accept
true/false and default to false, and className / class accept any ClassValue. Inference is checked by static
type tests under tests/types/ alongside the runtime suite.
Consequences. A change to the configuration types has to keep those type tests green; that is where a regression in inference shows up first.
Performance claims live in the benchmark suite
Context. "Faster than upstream" is the package's reason to exist, and a number written into a document rots the day the code changes.
Decision. No figure appears in this file, the README or the source. The first-party suite in
benchmarks/tailwind-variants runs the same workloads against tailwind-variants and class-variance-authority in
isolated subprocesses; its results ledger is the only place a ratio is recorded, and the README tells readers to run it.
Consequences. A hot-path change is judged by re-running the suite, not by argument. ARCHITECTURE.md states what a
shape guarantees; the suite says what it costs.
className wins over class
Context. Upstream applies both class and className when a call passes the two. Supporting that means reading
class on every call, and a component forwarding its className almost never passes class beside it, so every call
pays for a lookup that answers nothing.
Decision. When both are given, className is used and class is never read — on a resolver call, a slot call and a
compound entry, so one rule covers every place a class prop appears.
Consequences. A call forwarding className reads one property instead of two, which the override and simple
rows of the benchmark suite measure. The README's migration section lists the difference from upstream.
Not built, deliberately
A browser devtools extension, a VS Code extension, a CLI migration tool and CSS-in-JS integration were once listed as a roadmap. None is scheduled: the migration from upstream is an import change, the type surface already drives editor completion, and the package stays framework-agnostic by having no runtime beyond string work.
License
Released under the MIT License.