0.12.0
Minor Changes
- #1238 Breaking:
@codefast/tailwind-variantsis now published as@codefast/tv, and only the name changes. Swap the dependency and change everyfrom "@codefast/tailwind-variants"import tofrom "@codefast/tv"; the API and the version line carry on unchanged.@codefast/tailwind-variantsreceives no further releases.
0.11.0
Minor Changes
#1188 Every
@codefast/*package now requires Node.js 24.15 or later and drops Node 22. The packages ship as one set, so they share one floor instead of each sitting on its own 22.x release.@codefast/typescript-configremoves thenode22.jsonandnode22-dom.jsonoverlays; extend a preset alone.codefast audit enginesreports a published package whose floor differs from the highest one any published package declares.#1185 Breaking: three exported types are renamed or removed so each name says what the type is.
ExtendedVariantConfigis nowExtensionVariantConfig: it configures the extension, not the resolver it extends.SlotResolverPropsis removed; a slot resolver takesVariantSelection, the same selection a resolver call takes.HasBooleanVariantandVariantResolverResultare removed. Nothing read them:VariantValuealready admits a boolean for a"true"/"false"group, andReturnTypeof a resolver gives what a call returns.
#1182 Breaking: a slot call that passes both
classandclassNamenow usesclassNamealone, as a resolver call and a compound entry already did; it used to append both,classNamethenclass, soclasswon a conflict. One rule now covers every place a class prop appears:classNamewhen it is given,classotherwise.#1172 Breaking: the merge engine is now
cn, which replacestailwind-mergeas the peer dependency (cn >= 0.5.0).cnproduces the same output astailwind-mergeand merges a string no cache has seen several times faster, so a first render, a cold page load and aclassNameunique to its call all cost less. The exportedcnis the engine's own, whose argument cache answers a repeated call before any join. Installcnin place oftailwind-merge; custom class groups come fromextendTailwindMergeincn/config, and an app that still importstailwind-mergeelsewhere can alias it tocnso the bundle carries one engine.#1182 Breaking: a compound condition treats
undefined,nullandfalseas the same value, inside a list as well, in compound variants and compound slots of every configuration — the rule upstreamtailwind-variantsapplies. A slot configuration's compound variant onfalsenow matches an omitted variant, and a condition onfalseor[false]matches anullone.#1182 Breaking: a resolver or slot whose resolution has no classes now returns
"", as upstreamtailwind-variantsdoes, instead ofundefined.#1182 Breaking:
extendnow merges a configuration the way upstreamtailwind-variantsdoes. A variant value, a slot or a slot-map entry the child redeclares joins the parent's classes, parent first, instead of replacing them; a child'sbasejoins a parent'sslots.base; a slot child over a flat parent puts its own base before the parent's; a child'scompoundSlotsapply without redeclaringslots; and the child's variant names come first, invariantKeysand in the order their classes are emitted.#1162 Breaking:
twMergeConfigis removed. ThetwMergeoption now takestrue(the default engine'stwMerge),false(keep every declared class), or a merge function(classes: string) => stringthat replaces the merge fortvand for thecnacreateTVfactory returns. Custom class groups move totwMerge: extendTailwindMerge(config), built by the caller fromcn/configor any drop-in engine, so no bundle carries the configuration compiler unless the application builds one. The newClassMergertype names the function the option accepts.#1182 Breaking: a slot resolves the way upstream
tailwind-variantsresolves it. A compound slot reads the slot's own props, soitem({ disabled: true })no longer gets adisabled: falsecompound slot; a slot prop set tonullorundefinedkeeps the call's selection; a slot listed twice in a compound slot takes its classes twice on every path; an empty compound slot adds no stray space; and calling a slot withnullreturns its classes instead of throwing. The first call no longer reads the caller's props object when a slot is called later, so a reused props object cannot change what it resolved to.#1182 Breaking:
tv's types now describe what it returns for every configuration, not only for a fresh object literal.- A configuration held in a variable selects the same overload as the literal would: one with
slotsyields slot resolvers rather than a string, and one withextendkeeps the variants it inherits. - A resolver without variants takes no variant props, slots or not, so
card({ bogus: "x" })andcreateTV().tv({ base: "flex" })({ bogus: "x" })no longer compile,keyof VariantPropsof a slot-only resolver isnever, and extending it keeps the extension's literal values. Extending a resolver without slots and addingslotsyields slot resolvers. - A call without slots, and every slot resolver, is typed
string. VariantResolver<Variants, Slots>now selects between two exported shapes,FlatVariantResolverandSlotVariantResolver, and itsSlotsdefaults to none, so a resolver of one kind is no longer assignable to the other. Itsconfigisreadonly.TailwindVariantsFactoryistypeof tv, socreateTV().tvcarries exactlytv's overloads.- A slot map in a compound variant's
class/className, or in an extension'svariants, must name a declared slot. - A compound slot's condition accepts an array of alternatives, as compound variants already did.
- Readonly class arrays (
as const) are accepted wherever classes are.
- A configuration held in a variable selects the same overload as the literal would: one with
#1182 Breaking: a variant value is read the way upstream
tailwind-variantsreads it, the same in every lane. A slot component now selects key"0"for0instead of ignoring it;"",NaNand0nread as"false", so they select a boolean group'sfalsevalue and no other key; andnull, an array or an object selects nothing rather than looking up its string form. Only an omitted orundefinedvalue takes the configured default.#1182 Breaking: a numeric variant key is typed in both spellings the resolver reads it by, so
cols: { 1: "…" }acceptscols: "1"andcols: { "1": "…" }acceptscols: 1.VariantPropswidens to match: code that narrows such a prop to the numbers alone now has to admit the strings too.defaultVariantsalso accepts an explicitundefined.
Patch Changes
#1182 A resolver whose callers keep re-reading more selections than its cache holds no longer grows without bound: an entry read back from the older generation now counts toward the limit, together with the caller classes it remembers, so the store retires a generation the way a fresh one does. A generation's limit is sized so a table whose cells take their selection and
classNamefrom data still fits once those classes are counted.#1169 The
cnacreateTVfactory returns over a merge function of the caller's answers a repeated call of two strings — a static class list and the caller'sclassName— from a memo keyed on the strings as passed, so a repeat skips both the join and the merge engine's lookup of a freshly joined key.cxjoins its arguments in one pass, so a value that is not a string no longer restarts the join.#1182 A
tvfromcreateTVfalls back to each shared option the call leavesundefined, so{ twMerge: undefined }no longer overrides a sharedtwMerge: false.cacheResolutionsadmits an explicitundefined, so a possibly-undefined value can be forwarded underexactOptionalPropertyTypes.#1174 A call that passes a variant's default explicitly resolves from the same cache entry as one that omits it, so a page mixing
size: "default"with nosizeat all merges that answer once.#1175 A caller's class on a component without slots merges onto the selection's joined text. Under the default merge, a selection that has met several classes settles on reusing its shorter merged answer instead when merging dropped nothing but repeats, so the first class a selection meets costs one merge and nothing more. A selection also stops remembering caller classes past a fixed count, which keeps a long-lived selection's memory bounded.
#1176 A component without slots compiles its plan on the third call instead of the second, so one rendered exactly twice — common on a server render or a page that shows it twice — pays for no plan; a cold call without slots costs less than a compile, and the gap grows with the number of variants. Slot components still compile on their second call.
#1173 A resolver without slots remembers each selection once and the classes callers pass it inside that entry, so a repeated call builds no cache key, and a caller's class is remembered only from its second sighting — a
classNameunique to its call no longer churns the store.#1170 The call that compiles a resolver's plan — the third for a component without slots, the second for one with them — compiles only the variant values that call selects, plus each group's default, instead of every value the configuration declares; the rest compile the first time a call selects them. A component rendered only a few times pays far less, and a group nobody selects from costs nothing.
#1168 A resolver keeps answering from its cache where it used to stop: a compound-tested variant no longer runs out of keys however many distinct values callers pass, a configuration whose selection space is past one safe integer is still cached, and the store holds enough selections for a component whose variants and
classNamecome from data.#1167 A slot called with props that carry only
classorclassName— how a sub-component passes on theclassNameit was given — no longer re-resolves the slot on every call. An absent or empty class returns the slot's memoised answer, and a present one is merged onto the call's shared text, soroot({ className })costs a lookup instead of a full resolve and merge. Answers are unchanged.
0.10.0
Minor Changes
- #1068 Lower the Node.js floor from 24 to the lowest release the package, its dependencies and its full test suite run on:
22.12 for
@codefast/cliand@codefast/tailwind-variants, 22.18 for@codefast/diand@codefast/di-testing, and 22.22.2 for@codefast/theme,@codefast/trackingand@codefast/ui. Each floor is type-checked against what Node 22 ships and proven by running the package's tests on that release in CI.
Patch Changes
#1107 The README's benchmark section links the suite's generated
RESULTS.md, the committed baseline behind the "faster" claim.#1126
@codefast/tailwind-variantswill be renamed@codefast/tvin a future release, and the README now says so at the top. Only the name changes: when that release lands, replace the dependency (pnpm remove @codefast/tailwind-variants && pnpm add @codefast/tv) and change everyfrom "@codefast/tailwind-variants"import tofrom "@codefast/tv". Code that importstvandcnthrough@codefast/ui/lib/utilsinstead needs no change. Nothing changes in this release, and@codefast/tailwind-variantsstays the package to install until then.
0.9.1
Patch Changes
- #1028
tv({ extend })keeps the extended resolver's variant and slot names when the extension declares novariantsorslotsof its own. With nothing to infer from, the extension's schema fell back to its string-indexed constraint, so the merged props took any key:button({ sise: "sm" })andVariantProps<typeof button>accepted a misspelt variant, and a slot resolver accepted any slot name, though an unknown variant value was still caught. An extension that only addsbaseorcompoundVariantsis now typed exactly like the resolver it extends. Compounds and defaults no longer take part in inferring the extension's schema, so they cannot widen it either.
0.9.0
Minor Changes
- #976
engines.nodeis now>=24.0.0, up from>=22.12.0, and Node 22 is no longer supported. Node 24.0.0 is the first release with explicit resource management built in (using,await using,DisposableStack,AsyncDisposableStack,SuppressedError) and all of ES2025, so the packages use both as the platform ships them instead of shimming them for an older line, and the CI matrix runs the unit suite on 24.0.0 itself. Move to Node 24, or stay on the current minor while a deployment still runs Node 22.
Patch Changes
#977 The README states the browser floor: Chrome and Edge 136, Firefox 136, and Safari 18.4 or later, the first releases that ship every ES2025 builtin.
@codefast/di's README also says what a browser program without explicit resource management does: it keepsskipLibCheckon and callsdispose()instead ofawait using.#965
README.mdnow states TypeScript 7 or later as the floor for the package's types — the one compiler every@codefast/*package is built and checked with. No code or declaration changed.
0.8.1
Patch Changes
#892
4c97c5bThanks @thevuong! - Lower the monorepo's Node floor from 24 to 22.12, so the packages install and run on the active Node 22 LTS line.engines.nodebecomes>=22.12.0across every package — the floor the shared toolchain (oxlint, Vite, Vitest, TanStack Start) already requires. Development stays on the latest Node (.node-version) for speed, and a CI matrix exercises the floor and the active LTS directly, so the floor is a contract CI proves rather than one everyone has to run.@types/nodeis pinned to the floor's major (^22), with a workspace override holding the whole tree there so a dev tool's@types/node: "*"peer can no longer pull a newer major and mask an API the floor lacks. The floor stays mechanical, not advisory:@codefast/dikeeps its ownMapupsert helpers rather than the ES2025Map.prototype.getOrInsert(which would raise the floor to 26) and itslibstaysES2024.@codefast/cli's mirror step now calls thenode:pathfunctions directly instead of aliasing them, which the floor's types correctly flag as unbound methods.The shared
@codefast/typescript-configpresets pinlibandtargettoES2024(wasESNext) so the compiler's ECMAScript surface matches the Node floor: an ES2025 builtin such asMap.prototype.getOrInsertnow fails to type-check rather than compiling and crashing on Node 22.12.@codefast/diand@codefast/di-testingalready pinnedliband are unchanged.Internal subpath imports move from a
#/prefix to a bare#(#core/token, not#/core/token), and thepackage.json#importskeys become#*/#tests/*/#examples/*to match. Node's native ESM resolver rejects a#/-prefixed specifier withERR_INVALID_MODULE_SPECIFIERon the whole Node 22 line (and on Node 24 before 24.14), and each package ships those specifiers verbatim inside its publisheddist/*.jsfor a consumer's Node to resolve — so this rename is what actually lets the packages import on the new floor. Purely internal: a consumer's own import paths are unchanged.
0.8.0
Minor Changes
#824
98fc6c7Thanks @thevuong! -tv()no longer compiles at definition. The first call resolves straight from the configuration through a cold lane that answers exactly what the compiled plan answers, and the second call compiles the plan, so defining a component and rendering it once both cost less than upstream while every render after keeps its speed. Two visible consequences:configis a plain property rather than a defined read-only one, and a slot component returns the same slot object for a repeated selection from the second call on.The second call is cheaper too: a flat-lane variant group whose values are all strings is read in place rather than copied onto a prototype-less object, behind the type check the flat lane already makes. Resolvers expose
variantKeys, the variant names in declaration order, as upstream does.For editors,
VariantPropsis now read off the resolver's call signature instead of re-derived from its schema, which makes it far cheaper for the checker on large configurations, and every configuration field and option carries a doc comment that shows on hover.
0.7.1
Patch Changes
#791
37a212bThanks @thevuong! - Point the README's license badge and "License" section at the package's ownLICENSEfile instead of the monorepo root.#793
83cceebThanks @thevuong! - Make "MIT" in the README's License section the link to the package'sLICENSEfile.#796
ba04d27Thanks @thevuong! - Rewrite the README around one structure — what the package is, installation and requirements, a complete quick start, the concepts in learning order, then the documents and the license — with every API claim checked against the current code and no figures that go stale.#784
ad2f93aThanks @thevuong! - Ship the MITLICENSEfile in the published package.filesalready listed it, but the file was missing from the package directory, so the tarball had none.#809
6cd6a0eThanks @thevuong! -VariantSelection— the type a variant function accepts at its call site — now admits an explicitundefinedon every field, so a consumer underexactOptionalPropertyTypescan forward a possibly-undefined prop (variant={variant}) without first omitting it.VariantValues, whichdefaultVariantsdeclares, stays strict. Types only — no runtime change.
0.7.0
0.6.2
0.6.1
0.6.0
Minor Changes
#700
ea48ae2Thanks @thevuong! - Authoring a configuration is now type-checked as strictly as calling one. Three typos used to compile and then do nothing: adefaultVariantskey naming no variant, acompoundVariantskey naming no variant, and a variant class map naming no slot. Each failed the same silent way — nothing read the stray key, the compound never matched, the slot map was dropped — so a mistyped character removed a style with no error anywhere.The root cause was one overload.
extendwas optional onExtendedVariantConfig, which made the last overload a catch-all: a configuration the earlier three correctly rejected still matched it, andTBasewith nothing to infer from widened toVariantSchema, whose key isstring— so every mistyped name became legal again.extendis now required there, which is what that overload was always for. Alongside it,defaultVariantsandcompoundVariantsno longer act as inference sites for the variant schema (NoInfer), so a stray key is rejected instead of quietly widening the schema to include it.Two smaller corrections fall out.
defaultVariantsis typed by the newVariantValues<T>rather than the call-siteVariantSelection<T>, so it no longer accepts aclassNamea configuration has no use for. And in a slot configuration a variant's object value is now held to the declared slots —SlotClassValue<S>— because resolution has always read an object there as slot names rather than clsx conditions;basestays admissible whether or not it is declared, matching the plan that synthesises it.A configuration without slots keeps its clsx object values, and a compound condition naming an undeclared variant still resolves at runtime for JavaScript callers and merged configurations — it is only the typed authoring path that now rejects it, since no typed call could ever satisfy such a condition.
tests/types/common/config-authoring.test.tsholds all of this with@ts-expect-error, the first negative type tests in the package. The 110 existing assertions only ever proved what compiles, which is exactly how three gaps survived.One configuration shape stops compiling. Requiring
extendcloses the overload that used to accept anything, and that overload was also what accepted a configuration whose literal types had widened — a hoistedconst defaultVariants = { size: "sm" }, a hoistedcompoundVariantsarray, a spread of a shared partial. Those have type{ size: string }, which was never assignable to{ size?: "sm" }; they compiled only because the catch-all widened the schema to swallow them. Addas constto the hoisted value, or inline it.The error TypeScript reports for this is
Property 'extend' is missing, which names the last overload tried rather than the real mismatch. It is the same message a plain variant typo now produces. Nothing in this repository hit either case, but a consumer with a shared configuration fragment will.#700
93b18acThanks @thevuong! - A variant function now remembers what each selection resolved to, so a repeated selection skips both the plan walk andtailwind-merge. Against the previous build the resolution rows measure 1.08× to 11.9×, and againsttailwind-variantsthe suite geomean moves from 6.18× to 19.8×. The motivating measurement: in the merged lane most of the cost was never the merge algorithm —tailwind-mergecaches — but building and hashing the joined class string to look that cache up, which a key built from the selection avoids entirely.The key is a mixed-radix number, one digit per variant. A variant no compound tests is keyed by its group key, since two values sharing a key select the same classes; a variant a compound tests is keyed by the raw value, because a compound compares against what the caller passed and
trueand"true"share a group key while comparing differently. A call the key cannot represent — an axis past its capacity, a configuration too large to address in one safe integer, a clsx-shapedclassName— resolves the long way as before.Two consequences are worth knowing. A slot component called twice with the same selection gets back the same object of slot functions: stable enough for a React dependency array, and shared, so nothing may mutate it. And the store is bounded and keyed by the selection, so a component whose variant values are effectively unique per call fills it with entries nothing reads again — the new
cacheResolutions: falseoption turns it off for that component.Alongside it:
extendTailwindMergeis now memoised bytwMergeConfigidentity, so a design system handing one config to a hundred components builds one merge function instead of a hundred, each with its own cache; a slot resolution keeps only the props a compound can read rather than the caller's whole props object, which would otherwise pinchildrenfor as long as the entry lives; and each slot's merged text is memoised, so re-reading a slot no longer re-runs the merge.tvitself costs about a quarter of a microsecond more per component definition. The encoder is compiled on first resolution rather than intv, so a component that is defined and never rendered pays nothing for it.#701
710d533Thanks @thevuong! -@codefast/tailwind-variantsnow ships with no runtime dependencies of its own, matching whattailwind-variantshas always done. Two changes get it there.clsxis gone, replaced by a flattener inside the package. It is deliberately identical, corners included: abigintcontributes nothing despite being aClassValue, and an object's keys are read withfor…in, so an inherited enumerable one counts. Verified by running the behaviour sweep — every configuration, every variant value, every slot, with and without merging — againstmainand diffing: zero difference across 118,505 outcomes. The dependency was only ever reached at compile time anyway, since resolution stopped calling it when the plan was introduced.ClassValueis now declared here rather than re-exported from clsx, so the type survives the dependency leaving. Its shape is unchanged except thatClassDictionaryisRecord<string, unknown>rather than clsx'sRecord<string, any>— which means passing a function where a class value is expected is now a type error. It contributed nothing at runtime either way.tailwind-mergemoves from a dependency to a peer (>=3.0.0). A consumer who pins their own version now gets one copy at the version they chose, instead of a second one arriving underneath this package. Install it alongside —@codefast/uialready does on your behalf.#700
d0dd326Thanks @thevuong! - Compile the configuration once, intv, instead of re-deriving it on every resolver call.tvnow builds a plan. Variant groups become an array of entries whose default classes are already looked up, compound variants become flat condition lists whose fallbacks are already resolved, and every class value is flattened to a string. Resolution reads monomorphic fields and concatenates strings, so the per-call work that used to happen —Object.keysper compound variant, a dictionary lookup per variant per slot, an intermediate array plus a spread intoclsx— is gone.Slot resolution is also inverted. A slot map names only a few slots, so having each of N slots scan every variant meant mostly-missing lookups. Each variant value now carries the slot positions it targets, and one pass distributes classes into a per-slot buffer that every resolver of that call shares; a slot called without its own props just reads its entry. Compound slots ride the same pass.
Measured against the previous release on
benchmarks/tailwind-variants(paired A/B, one subprocess per side per scenario, three passes with the order alternated, median of per-pass ratios): every one of the sixteen scenarios is faster, geometric mean 2.86×.shape without tailwind-mergewith extreme-slots9.64× 5.99× slots5.55× 3.48× compound-slots4.94× 3.21× complex2.59× 2.00× simple/extends/create-tv/extreme2.22×–2.33× 1.56×–1.89× The merge-enabled rows gain least because merging, not resolution, is what is left in them. The suite's A/A noise floor on the same machine is ±1%.
The trade is a slower
tvcall: flattening every class value and precomputing slot positions costs roughly 400ns more for a simple config and ~3.4µs for a ten-slot one. That is once per component definition, at module load, and against a slot resolution that got ~1.6µs cheaper it pays for itself after about two renders.One behavioural change, in a corner: a configuration whose classes are all truthy but render to nothing —
tv({ base: {} })— now returnsundefinedwithtwMergeenabled, where it previously returned"". It already returnedundefinedwithtwMergedisabled, soundefinedis now what "no classes" means either way.
Patch Changes
#700
fe7e9e4Thanks @thevuong! - A variant value naming anObject.prototypemember no longer reaches it. A compiled variant group is indexed by whatever a caller passes, and it was a plain object — sogroup["toString"]answered with a function instead ofundefined. The flat lane concatenated that function's source text into the class string, and the slot lane read slot positions offObject.prototypeand threw:tv({ base: "block", variants: { size: { sm: "p-2" } } })({ size: "toString" }) → "block function toString() { [native code] }" tv({ slots: { base: "rounded" }, … })({ size: "__proto__" }).base() → TypeError: Cannot read properties of undefined (reading 'length')Groups and the slot index map are now compiled onto prototype-less objects, which closes both resolvers and the selection encoder at once since all three read the same object. It costs roughly twice what reusing the source object did, once per component definition.
Two smaller things fall out of the same reading. A value the group does not answer is no longer memoised into the id table, which a long-lived server rendering user-supplied values would otherwise grow without bound; and inherited keys no longer consume the ids a group's declared values need, which used to disable a resolver's cache permanently after a few junk values.
0.5.0
Patch Changes
#676
641e233Thanks @thevuong! - Collapse thetypesanddefaultlanes ofpackage.json#importsfrom fallback arrays to single strings.Node resolves an imports array by taking the first candidate it can parse, without checking that the file exists and without falling through — a specifier whose first candidate is missing throws
ERR_MODULE_NOT_FOUNDrather than trying the second../dist/*/index.jsand./dist/*/index.d.tscould therefore never be reached, so they read as a safety net that does not exist. Thesourcelane keeps its extension candidates, which onlytscand Vite read and both probe.
0.5.0-canary.9
Patch Changes
#676
641e233Thanks @thevuong! - Collapse thetypesanddefaultlanes ofpackage.json#importsfrom fallback arrays to single strings.Node resolves an imports array by taking the first candidate it can parse, without checking that the file exists and without falling through — a specifier whose first candidate is missing throws
ERR_MODULE_NOT_FOUNDrather than trying the second../dist/*/index.jsand./dist/*/index.d.tscould therefore never be reached, so they read as a safety net that does not exist. Thesourcelane keeps its extension candidates, which onlytscand Vite read and both probe.
0.5.0-canary.8
0.5.0-canary.7
0.5.0-canary.6
1.0.0-canary.7
1.0.0-canary.6
0.5.0-canary.5
Showing the latest 20 releases; the full changelog on GitHub has 48 more releases.