cn claims 30x for the call your components make most, and 3x when nothing is cached
cn is a new engine for Tailwind class merging and conflict resolution. It replaces tailwind-merge and clsx. Same APIs. Full parity. And it is 30× faster.
At a glance
- What is it?
- cn is a zero-dependency replacement for clsx and tailwind-merge that merges Tailwind classes and resolves conflicts, published by the shadcn-ui organisation and maintained with aidenybai. Its parity claim is checked by 356,000 differential tests, its speed claim rests on identity caching, and its Tailwind v4 requirement locks out everyone still on v3.
- Who is it for?
- cn is a reasonable swap for a Tailwind v4 project that already depends on shadcn/ui, since the API is identical and the size is gated at release. Check two things first: whether your project is still on Tailwind v3, where cn does not apply, and whether your class strings are built at runtime, since `cn build` cannot see a dynamically concatenated class.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 13 days ago.
- What is it written in?
- Mainly TypeScript, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.
Star history
- shadcn-ui/cn1,752 ★ · +192
| Repository | 2026-09-21 | 2026-11-15 |
|---|---|---|
| shadcn-ui/cn | 1.6k | 1.8k |
192 Stars in the last 55 days, measured from the daily GitHub snapshot. Compare with other projects
Editorial analysis
The headline number is the first row of a seven row table
The 30x claim comes from one row: the call your components make most, 320 ns against 10 ns. The same table lists six other workloads and the ratios fall off quickly from there. A cache hit on the same classes as the last render is 14 ns against 7 ns, or 1.9x. Warm typical component strings are 13 ns against 7 ns, also 1.9x. A cold render with many arbitrary values is 3.4 µs against 1.1 µs, which is 3.0x, and a cold render with server-side rendering style unique strings is 2.3 µs against 360 ns, or 6.4x. The very first call on page load is 3.2 ms against 0.4 ms, 7x.
So the honest reading is that the speedup depends entirely on whether the input repeats. Warm and cached calls land between 1.9x and 30x, cold calls land between 3x and 7x, and only one row exceeds 100x.
The methodology is stated above the table: each library is exercised in its own isolated process with its own warmup, the best of five runs is kept, and the tables can be regenerated with `pnpm bench`. The write-up links the details to a methodology section in docs/how-it-works.md, so the numbers are checkable rather than asserted.
The 172x row measures identity verification, not merging
One row sits far above the rest: thousands of recurring strings, described as a real repository's working set, at 2.4 µs against 14 ns, which is 172x. The footnote under the table explains the mechanism, and it is the most useful paragraph in the file.
A component call looks like `cn(base, variant, condition && extra)` with stable class strings, which is the shape almost every component call has. The engine learns repeated call sequences, so inside a render loop subsequent calls verify by identity and skip the work entirely. That is a cache over call sites, not a faster merge algorithm, and it is the reason the recurring-string row is two orders of magnitude better than the cold rows: the cold rows are the ones that actually pay for parsing and conflict resolution.
This also sets the limit. Identity verification needs the same argument values to arrive again, so a project that composes class strings fresh on every render, with an interpolated size or a template literal, lands in the cold rows and the realistic ratio is the 3x to 7x range. The corpus benchmark in the next section is an attempt to measure the realistic case, since it replays calls harvested from code that was not written for this cache.
The corpus benchmark needs 58 repositories and no visible harvest script
The synthetic rows are acknowledged as synthetic, and a second measurement is offered for real code. `pnpm bench:corpus` replays every `cn()` call harvested from 58 open source codebases, 144,265 calls in total, through each library, with one isolated process per library and per repository, and prints a per-repository table. The geometric mean across the 58 repositories is 37x.
The 37x figure is the better headline than the 30x, and it is also the harder number to check, because the corpus is a snapshot. It lives outside the repository, there is no stated date for the harvest, and the root package exposes no script for refreshing it: the scripts list contains bench and bench:corpus, which replay a corpus, and nothing named for collecting one. So the corpus ages silently between harvests, and the 37x describes the code those repositories contained at the time.
Bundle size is the third claim and the least quantified one. cn ships 26 KB minified and is said to parse the least JavaScript of the setups compared, but no size for clsx plus tailwind-merge appears in the table, so the size advantage has to be measured rather than read.
Parity is claimed for every input, with one exception in the mapping
The compatibility claim is that cn produces the same output as tailwind-merge for every input, verified with 356,000 differential tests. The API surface is mapped export by export in a table, and almost every row is a straight copy. `twMerge(...)` and `twJoin(...)` keep their names and are described as identical. `extendTailwindMerge(ext)` keeps its name and moves to `cn/config`. `createTailwindMerge(fn)` becomes `createTwMerge(fn)` from `cn/config`, `getDefaultConfig()` becomes `defaultConfig()`, and `fromTheme`, `validators` and `mergeConfigs` keep their names.
The one row that says not supported is `experimentalParseClassName`. Everything else in that table is a rename or a relocation, so a migration is a matter of changing an import path, and the one gap is an experimental parser that existed to let callers inspect how a class string was classified.
Theme configuration follows the same pattern. `cn/config` accepts the identical `{ extend, override, prefix }` shape under the same name, so `extendTailwindMerge` becomes `createCn` with the same object, custom validator functions work as they did, and Tailwind v4 prefixes are handled by passing `prefix: "tw"`. What this means in practice is that a project already customizing tailwind-merge does not have to learn a second configuration language.
Tailwind v3 is the boundary, and it is not a soft one
The gotchas section is short and one line decides whether you can switch at all. cn supports Tailwind CSS v4, like tailwind-merge v3. On Tailwind v3, stay with tailwind-merge v2.
That means the migration path in the rest of the file, the CLI command and the one-file wrapper replacement, only applies to projects already on v4. A project on Tailwind v3 reading the rest of this page has no upgrade offered by the project at all, which is a real ceiling on the audience even though nothing in the pitch mentions it.
The remaining gotchas are inherited behaviours rather than new ones. Classes that merely look like Tailwind utilities, with `text-2xs` as the example, are treated as Tailwind utilities, which the file points at tailwind-merge's own limitations page for comparison. With `cn build`, dynamically constructed class names such as `"p-" + size` cannot be detected, and the guidance is to use `--safelist`, which is the same rule Tailwind applies to its own scanner. And the CLI needs Node 20 or newer, matching the workspace engines field of node >=20.
Bundle size is a release gate, and the tables are generated
The workspace root is where the engineering practice shows. Its release script is a chain: `pnpm run typecheck && pnpm run test && pnpm run size && changeset publish`. Size is not a report someone reads, it is a gate that has to pass before a version is published, which is the strongest structural answer to a library that competes on parse cost.
The test script is also indirect in an interesting way: it builds the cn package first and then runs the conformance package's tests against the result, while a separate `test:src` runs the source variant. So the default gate exercises the built artifact, not the working tree.
Two scripts name generated inputs. `compile-tables` builds the class tables inside the cn package, and `vendor-config` runs inside the conformance package, which is the piece that compares cn against the libraries it replaces. There is also a `speedlab` script with no description anywhere in the file. The release tooling is changesets, with both @changesets/cli and a GitHub changelog plugin in devDependencies, and the root package is named cn-workspace, private, and pinned to pnpm 10.28.2 with a pnpm-lock.yaml and pnpm-workspace.yaml at the root.
The releases move quickly for a 0.x library: [email protected] on 2026-09-21, then [email protected] and [email protected] twenty-five minutes apart on 2026-09-22, with further commits after that on 2026-09-28.
Migration is one file, and the fallback is an alias
Install is a single command, `npm i cn`, and the package has zero dependencies and no framework requirement, working with React, Vue, Svelte, Solid, Astro or plain server templates in browsers, Node, Bun, Deno and edge runtimes. Any Tailwind project can use it, and shadcn/ui itself is not required.
For an existing shadcn/ui project the CLI does the work:
npx shadcn@latest migrate cnDoing it by hand touches one file. A typical `lib/utils.ts` defines a wrapper that takes `ClassValue[]` inputs and returns `twMerge(clsx(inputs))`, imported from clsx and tailwind-merge. The replacement is a single re-export from cn, after which clsx and tailwind-merge are removed from the dependency list. If other packages still import them, the project is told to alias those imports to cn so that only one implementation ships in the bundle, with docs/aliasing.md holding the mechanics.
The optional extra is `cn build`, documented separately, for people who want a smaller artifact at the same speed. It ships as a Vite plugin and a Next.js config wrapper so the tables follow the sources during development with nothing to script. The trade is the one in the gotchas: a build step that must see your class strings, which rules out runtime concatenation.
Editorial conclusion
cn is a reasonable swap for a Tailwind v4 project that already depends on shadcn/ui, since the API is identical and the size is gated at release. Check two things first: whether your project is still on Tailwind v3, where cn does not apply, and whether your class strings are built at runtime, since `cn build` cannot see a dynamically concatenated class. Teams that only want the merge behaviour can take the drop-in change and ignore the build plugin.
Frequently asked questions
Can cn replace clsx and tailwind-merge in an existing project?
Yes, for Tailwind v4 projects. The API keeps the same names, `twMerge`, `twJoin`, `extendTailwindMerge` and the rest, and the usual wrapper in lib/utils.ts is replaced by a re-export from cn. The CLI command is `npx shadcn@latest migrate cn`.
What does cn require from Tailwind and Node?
Tailwind CSS v4, matching tailwind-merge v3. On Tailwind v3 the guidance is to stay with tailwind-merge v2. The CLI needs Node 20 or newer, and the workspace declares engines node >=20.
Does cn support every tailwind-merge export?
All of them except one. The mapping table lists `experimentalParseClassName` as not supported; the rest keep their names or move to `cn/config`, with `createTailwindMerge` renamed to `createTwMerge` and `getDefaultConfig` to `defaultConfig`.
How big is the cn package?
26 KB minified, and it is described as shipping the least JavaScript to parse of the setups compared. No size for clsx plus tailwind-merge appears in the benchmark table, and the size check is a release gate in the workspace scripts.
What does cn build do, and what does it break?
It is a build step, shipped as a Vite plugin and a Next.js config wrapper, that keeps the tables in step with your sources. The documented cost is that dynamically constructed class names such as `"p-" + size` cannot be detected, so you use `--safelist`.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/shadcn-ui-cn)Star history chart for your README
[](https://hysenlabs.com/projects/shadcn-ui-cn)Was this useful?