Skip to content
codefastlabs

Command Palette

Search for a command to run...

@codefast/tvv0.12.0· Changelog

@codefast/tailwind-variants

0.12.0

Minor Changes

  • #1238 Breaking: @codefast/tailwind-variants is now published as @codefast/tv, and only the name changes. Swap the dependency and change every from "@codefast/tailwind-variants" import to from "@codefast/tv"; the API and the version line carry on unchanged. @codefast/tailwind-variants receives 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-config removes the node22.json and node22-dom.json overlays; extend a preset alone. codefast audit engines reports 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.

    • ExtendedVariantConfig is now ExtensionVariantConfig: it configures the extension, not the resolver it extends.
    • SlotResolverProps is removed; a slot resolver takes VariantSelection, the same selection a resolver call takes.
    • HasBooleanVariant and VariantResolverResult are removed. Nothing read them: VariantValue already admits a boolean for a "true"/"false" group, and ReturnType of a resolver gives what a call returns.
  • #1182 Breaking: a slot call that passes both class and className now uses className alone, as a resolver call and a compound entry already did; it used to append both, className then class, so class won a conflict. One rule now covers every place a class prop appears: className when it is given, class otherwise.

  • #1172 Breaking: the merge engine is now cn, which replaces tailwind-merge as the peer dependency (cn >= 0.5.0). cn produces the same output as tailwind-merge and merges a string no cache has seen several times faster, so a first render, a cold page load and a className unique to its call all cost less. The exported cn is the engine's own, whose argument cache answers a repeated call before any join. Install cn in place of tailwind-merge; custom class groups come from extendTailwindMerge in cn/config, and an app that still imports tailwind-merge elsewhere can alias it to cn so the bundle carries one engine.

  • #1182 Breaking: a compound condition treats undefined, null and false as the same value, inside a list as well, in compound variants and compound slots of every configuration — the rule upstream tailwind-variants applies. A slot configuration's compound variant on false now matches an omitted variant, and a condition on false or [false] matches a null one.

  • #1182 Breaking: a resolver or slot whose resolution has no classes now returns "", as upstream tailwind-variants does, instead of undefined.

  • #1182 Breaking: extend now merges a configuration the way upstream tailwind-variants does. 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's base joins a parent's slots.base; a slot child over a flat parent puts its own base before the parent's; a child's compoundSlots apply without redeclaring slots; and the child's variant names come first, in variantKeys and in the order their classes are emitted.

  • #1162 Breaking: twMergeConfig is removed. The twMerge option now takes true (the default engine's twMerge), false (keep every declared class), or a merge function (classes: string) => string that replaces the merge for tv and for the cn a createTV factory returns. Custom class groups move to twMerge: extendTailwindMerge(config), built by the caller from cn/config or any drop-in engine, so no bundle carries the configuration compiler unless the application builds one. The new ClassMerger type names the function the option accepts.

  • #1182 Breaking: a slot resolves the way upstream tailwind-variants resolves it. A compound slot reads the slot's own props, so item({ disabled: true }) no longer gets a disabled: false compound slot; a slot prop set to null or undefined keeps 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 with null returns 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 slots yields slot resolvers rather than a string, and one with extend keeps the variants it inherits.
    • A resolver without variants takes no variant props, slots or not, so card({ bogus: "x" }) and createTV().tv({ base: "flex" })({ bogus: "x" }) no longer compile, keyof VariantProps of a slot-only resolver is never, and extending it keeps the extension's literal values. Extending a resolver without slots and adding slots yields slot resolvers.
    • A call without slots, and every slot resolver, is typed string.
    • VariantResolver<Variants, Slots> now selects between two exported shapes, FlatVariantResolver and SlotVariantResolver, and its Slots defaults to none, so a resolver of one kind is no longer assignable to the other. Its config is readonly.
    • TailwindVariantsFactory is typeof tv, so createTV().tv carries exactly tv's overloads.
    • A slot map in a compound variant's class/className, or in an extension's variants, 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.
  • #1182 Breaking: a variant value is read the way upstream tailwind-variants reads it, the same in every lane. A slot component now selects key "0" for 0 instead of ignoring it; "", NaN and 0n read as "false", so they select a boolean group's false value and no other key; and null, an array or an object selects nothing rather than looking up its string form. Only an omitted or undefined value takes the configured default.

  • #1182 Breaking: a numeric variant key is typed in both spellings the resolver reads it by, so cols: { 1: "…" } accepts cols: "1" and cols: { "1": "…" } accepts cols: 1. VariantProps widens to match: code that narrows such a prop to the numbers alone now has to admit the strings too. defaultVariants also accepts an explicit undefined.

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 className from data still fits once those classes are counted.

  • #1169 The cn a createTV factory returns over a merge function of the caller's answers a repeated call of two strings — a static class list and the caller's className — 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. cx joins its arguments in one pass, so a value that is not a string no longer restarts the join.

  • #1182 A tv from createTV falls back to each shared option the call leaves undefined, so { twMerge: undefined } no longer overrides a shared twMerge: false. cacheResolutions admits an explicit undefined, so a possibly-undefined value can be forwarded under exactOptionalPropertyTypes.

  • #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 no size at 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 className unique 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 className come from data.

  • #1167 A slot called with props that carry only class or className — how a sub-component passes on the className it 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, so root({ 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/cli and @codefast/tailwind-variants, 22.18 for @codefast/di and @codefast/di-testing, and 22.22.2 for @codefast/theme, @codefast/tracking and @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-variants will be renamed @codefast/tv in 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 every from "@codefast/tailwind-variants" import to from "@codefast/tv". Code that imports tv and cn through @codefast/ui/lib/utils instead needs no change. Nothing changes in this release, and @codefast/tailwind-variants stays 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 no variants or slots of 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" }) and VariantProps<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 adds base or compoundVariants is 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.node is 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 keeps skipLibCheck on and calls dispose() instead of await using.

  • #965 README.md now 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 4c97c5b Thanks @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.node becomes >=22.12.0 across 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/node is 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/di keeps its own Map upsert helpers rather than the ES2025 Map.prototype.getOrInsert (which would raise the floor to 26) and its lib stays ES2024. @codefast/cli's mirror step now calls the node:path functions directly instead of aliasing them, which the floor's types correctly flag as unbound methods.

    The shared @codefast/typescript-config presets pin lib and target to ES2024 (was ESNext) so the compiler's ECMAScript surface matches the Node floor: an ES2025 builtin such as Map.prototype.getOrInsert now fails to type-check rather than compiling and crashing on Node 22.12. @codefast/di and @codefast/di-testing already pinned lib and are unchanged.

    Internal subpath imports move from a #/ prefix to a bare # (#core/token, not #/core/token), and the package.json#imports keys become #*/#tests/*/#examples/* to match. Node's native ESM resolver rejects a #/-prefixed specifier with ERR_INVALID_MODULE_SPECIFIER on the whole Node 22 line (and on Node 24 before 24.14), and each package ships those specifiers verbatim inside its published dist/*.js for 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 98fc6c7 Thanks @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: config is 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, VariantProps is 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 37a212b Thanks @thevuong! - Point the README's license badge and "License" section at the package's own LICENSE file instead of the monorepo root.

  • #793 83cceeb Thanks @thevuong! - Make "MIT" in the README's License section the link to the package's LICENSE file.

  • #796 ba04d27 Thanks @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 ad2f93a Thanks @thevuong! - Ship the MIT LICENSE file in the published package. files already listed it, but the file was missing from the package directory, so the tarball had none.

  • #809 6cd6a0e Thanks @thevuong! - VariantSelection — the type a variant function accepts at its call site — now admits an explicit undefined on every field, so a consumer under exactOptionalPropertyTypes can forward a possibly-undefined prop (variant={variant}) without first omitting it. VariantValues, which defaultVariants declares, stays strict. Types only — no runtime change.

0.7.0

0.6.2

0.6.1

0.6.0

Minor Changes

  • #700 ea48ae2 Thanks @thevuong! - Authoring a configuration is now type-checked as strictly as calling one. Three typos used to compile and then do nothing: a defaultVariants key naming no variant, a compoundVariants key 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. extend was optional on ExtendedVariantConfig, which made the last overload a catch-all: a configuration the earlier three correctly rejected still matched it, and TBase with nothing to infer from widened to VariantSchema, whose key is string — so every mistyped name became legal again. extend is now required there, which is what that overload was always for. Alongside it, defaultVariants and compoundVariants no 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. defaultVariants is typed by the new VariantValues<T> rather than the call-site VariantSelection<T>, so it no longer accepts a className a 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; base stays 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.ts holds 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 extend closes the overload that used to accept anything, and that overload was also what accepted a configuration whose literal types had widened — a hoisted const defaultVariants = { size: "sm" }, a hoisted compoundVariants array, 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. Add as const to 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 93b18ac Thanks @thevuong! - A variant function now remembers what each selection resolved to, so a repeated selection skips both the plan walk and tailwind-merge. Against the previous build the resolution rows measure 1.08× to 11.9×, and against tailwind-variants the 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-merge caches — 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 true and "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-shaped className — 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: false option turns it off for that component.

    Alongside it: extendTailwindMerge is now memoised by twMergeConfig identity, 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 pin children for 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.

    tv itself costs about a quarter of a microsecond more per component definition. The encoder is compiled on first resolution rather than in tv, so a component that is defined and never rendered pays nothing for it.

  • #701 710d533 Thanks @thevuong! - @codefast/tailwind-variants now ships with no runtime dependencies of its own, matching what tailwind-variants has always done. Two changes get it there.

    clsx is gone, replaced by a flattener inside the package. It is deliberately identical, corners included: a bigint contributes nothing despite being a ClassValue, and an object's keys are read with for…in, so an inherited enumerable one counts. Verified by running the behaviour sweep — every configuration, every variant value, every slot, with and without merging — against main and 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.

    ClassValue is now declared here rather than re-exported from clsx, so the type survives the dependency leaving. Its shape is unchanged except that ClassDictionary is Record<string, unknown> rather than clsx's Record<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-merge moves 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/ui already does on your behalf.

  • #700 d0dd326 Thanks @thevuong! - Compile the configuration once, in tv, instead of re-deriving it on every resolver call.

    tv now 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.keys per compound variant, a dictionary lookup per variant per slot, an intermediate array plus a spread into clsx — 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-merge with
    extreme-slots 9.64× 5.99×
    slots 5.55× 3.48×
    compound-slots 4.94× 3.21×
    complex 2.59× 2.00×
    simple / extends / create-tv / extreme 2.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 tv call: 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 returns undefined with twMerge enabled, where it previously returned "". It already returned undefined with twMerge disabled, so undefined is now what "no classes" means either way.

Patch Changes

  • #700 fe7e9e4 Thanks @thevuong! - A variant value naming an Object.prototype member no longer reaches it. A compiled variant group is indexed by whatever a caller passes, and it was a plain object — so group["toString"] answered with a function instead of undefined. The flat lane concatenated that function's source text into the class string, and the slot lane read slot positions off Object.prototype and 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 641e233 Thanks @thevuong! - Collapse the types and default lanes of package.json#imports from 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_FOUND rather than trying the second. ./dist/*/index.js and ./dist/*/index.d.ts could therefore never be reached, so they read as a safety net that does not exist. The source lane keeps its extension candidates, which only tsc and Vite read and both probe.

0.5.0-canary.9

Patch Changes

  • #676 641e233 Thanks @thevuong! - Collapse the types and default lanes of package.json#imports from 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_FOUND rather than trying the second. ./dist/*/index.js and ./dist/*/index.d.ts could therefore never be reached, so they read as a safety net that does not exist. The source lane keeps its extension candidates, which only tsc and 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.