feat: add cx function and refactor cn to use tailwind-merge (#278)

- Add cx function for simple class name concatenation (like clsx)
- Refactor cn to only support tailwind-merge (from tw-merge.js)
- Remove cnBase export, replaced with cx
- Update all internal references from cnBase to cx
- Add comprehensive tests for cx and cn functions
- Add cx benchmarks to benchmark.js
- Update type definitions for all entry points

Author: jrgarciadev

benchmark.js

@@ -3,7 +3,7 @@ import Benchmark from "benchmark";
 import {cva} from "class-variance-authority";
 import {extendTailwindMerge} from "tailwind-merge";
 
-import {tv} from "./src/index.js";
+import {tv, cx, cn} from "./src/index.js";
 
 const suite = new Benchmark.Suite();
 
@@ -375,6 +375,38 @@ const cvaNoMerge = {
 
 const cvaMerge = extendTailwindMerge({extend: twMergeConfig});
 
+// Test data for cx benchmarks
+const simpleClasses = ["text-xl", "font-bold", "text-center", "px-4", "py-2"];
+const arrayClasses = [["px-4", "py-2"], "bg-blue-500", ["rounded-lg", "shadow-md"]];
+const objectClasses = {
+  "text-sm": true,
+  "font-bold": false,
+  "bg-green-200": 1,
+  "m-0": 0,
+  "px-2": true,
+  "py-2": true,
+};
+const mixedClasses = [
+  "text-lg",
+  ["px-3", {"hover:bg-yellow-300": true, "focus:outline-none": false}],
+  {"rounded-md": true, "shadow-md": null},
+  "leading-tight",
+];
+const nestedArrays = [
+  "px-4",
+  ["py-2", ["bg-blue-500", ["rounded-lg", false, ["shadow-md", ["text-white"]]]]],
+];
+const withFalsy = [
+  "text-xl",
+  false && "font-bold",
+  "text-center",
+  undefined,
+  null,
+  0,
+  "",
+  "px-4",
+];
+
 // add tests
 suite
   .add("TV without slots & tw-merge (enabled)", function () {
@@ -423,6 +455,45 @@ suite
     cvaNoMerge.fallback();
     cvaNoMerge.image();
   })
+  .add("cx - simple strings", function () {
+    cx(...simpleClasses);
+  })
+  .add("cx - arrays", function () {
+    cx(...arrayClasses);
+  })
+  .add("cx - objects", function () {
+    cx(objectClasses);
+  })
+  .add("cx - mixed arguments", function () {
+    cx(...mixedClasses);
+  })
+  .add("cx - nested arrays", function () {
+    cx(...nestedArrays);
+  })
+  .add("cx - with falsy values", function () {
+    cx(...withFalsy);
+  })
+  .add("cn - simple strings (with tw-merge)", function () {
+    cn(...simpleClasses)({twMerge: true});
+  })
+  .add("cn - arrays (with tw-merge)", function () {
+    cn(...arrayClasses)({twMerge: true});
+  })
+  .add("cn - objects (with tw-merge)", function () {
+    cn(objectClasses)({twMerge: true});
+  })
+  .add("cn - mixed arguments (with tw-merge)", function () {
+    cn(...mixedClasses)({twMerge: true});
+  })
+  .add("cn - nested arrays (with tw-merge)", function () {
+    cn(...nestedArrays)({twMerge: true});
+  })
+  .add("cn - with falsy values (with tw-merge)", function () {
+    cn(...withFalsy)({twMerge: true});
+  })
+  .add("cn - simple strings (without tw-merge)", function () {
+    cn(...simpleClasses)({twMerge: false});
+  })
 
   // add listeners
   .on("cycle", function (event) {

src/__tests__/cn.test.ts

@@ -1,43 +1,179 @@
 import {expect, describe, test} from "@jest/globals";
 
-import {cnBase as cnFull} from "../index";
-import {cn as cnLite} from "../lite";
-import {cn as cnUtils} from "../utils";
-
-const variants = [
-  {name: "full - tailwind-merge", cn: cnFull},
-  {name: "lite - without tailwind-merge", cn: cnLite},
-  {name: "utils - without tailwind-merge", cn: cnUtils},
+import {cn as cnWithMerge, cx as cxFull} from "../index";
+import {cn as cnLite, cx as cxLite} from "../lite";
+import {cx as cxUtils} from "../utils";
+
+const cxVariants = [
+  {name: "main index", cx: cxFull},
+  {name: "lite", cx: cxLite},
+  {name: "utils", cx: cxUtils},
 ];
 
-describe.each(variants)("cn function - $name", ({cn}) => {
+describe("cn function from lite (simple concatenation)", () => {
+  test("should join strings and ignore falsy values", () => {
+    expect(cnLite("text-xl", false && "font-bold", "text-center")()).toBe("text-xl text-center");
+    expect(cnLite("text-xl", undefined, null, 0, "")()).toBe("text-xl 0");
+  });
+
+  test("should join arrays of class names", () => {
+    expect(cnLite(["px-4", "py-2"], "bg-blue-500")()).toBe("px-4 py-2 bg-blue-500");
+    expect(cnLite(["px-4", false, ["hover:bg-red-500", null, "rounded-lg"]])()).toBe(
+      "px-4 hover:bg-red-500 rounded-lg",
+    );
+  });
+
+  test("should handle nested arrays", () => {
+    expect(cnLite(["px-4", ["py-2", ["bg-blue-500", ["rounded-lg", false, ["shadow-md"]]]]])()).toBe(
+      "px-4 py-2 bg-blue-500 rounded-lg shadow-md",
+    );
+  });
+
+  test("should join objects with truthy values as keys", () => {
+    expect(cnLite({"text-sm": true, "font-bold": false, "bg-green-200": 1, "m-0": 0})()).toBe(
+      "text-sm bg-green-200",
+    );
+  });
+
+  test("should handle mixed arguments correctly", () => {
+    expect(
+      cnLite(
+        "text-lg",
+        ["px-3", {"hover:bg-yellow-300": true, "focus:outline-none": false}],
+        {"rounded-md": true, "shadow-md": null},
+        "leading-tight",
+      )(),
+    ).toBe("text-lg px-3 hover:bg-yellow-300 rounded-md leading-tight");
+  });
+
+  test("should handle numbers and bigint", () => {
+    expect(cnLite(123, "text-base", 0n, {border: true})()).toBe("123 text-base 0 border");
+  });
+
+  test("should return undefined for no input", () => {
+    expect(cnLite()()).toBeUndefined();
+  });
+
+  test("should return '0' for zero and ignore other falsy", () => {
+    expect(cnLite(false, null, undefined, "", 0)()).toBe("0");
+  });
+
+  test("should normalize template strings with irregular whitespace", () => {
+    const input = `
+      px-4
+      py-2
+
+      bg-blue-500
+        rounded-lg
+    `;
+
+    expect(cnLite(input)()).toBe("px-4 py-2 bg-blue-500 rounded-lg");
+
+    expect(
+      cnLite(
+        ` text-center
+          font-semibold  `,
+        ["text-sm", `   uppercase   `],
+        {"shadow-lg": true, "opacity-50": false},
+      )(),
+    ).toBe("text-center font-semibold text-sm uppercase shadow-lg");
+  });
+
+  test("should handle empty and falsy values correctly", () => {
+    expect(cnLite("", null, undefined, false, NaN, 0, "0")()).toBe("0 0");
+  });
+});
+
+describe("cn function with tailwind-merge (main index)", () => {
+  test("should merge conflicting tailwind classes when twMerge is true", () => {
+    const result = cnWithMerge("px-2", "px-4", "py-2")({twMerge: true});
+
+    expect(result).toBe("px-4 py-2");
+  });
+
+  test("should not merge classes when twMerge is false", () => {
+    const result = cnWithMerge("px-2", "px-4", "py-2")({twMerge: false});
+
+    expect(result).toBe("px-2 px-4 py-2");
+  });
+
+  test("should merge text color classes", () => {
+    const result = cnWithMerge("text-red-500", "text-blue-500")({twMerge: true});
+
+    expect(result).toBe("text-blue-500");
+  });
+
+  test("should merge background color classes", () => {
+    const result = cnWithMerge("bg-red-500", "bg-blue-500")({twMerge: true});
+
+    expect(result).toBe("bg-blue-500");
+  });
+
+  test("should merge multiple conflicting classes", () => {
+    const result = cnWithMerge("px-2 py-1 text-sm", "px-4 py-2 text-lg")({twMerge: true});
+
+    expect(result).toBe("px-4 py-2 text-lg");
+  });
+
+  test("should handle non-conflicting classes", () => {
+    const result = cnWithMerge("px-2", "py-2", "text-sm")({twMerge: true});
+
+    expect(result).toBe("px-2 py-2 text-sm");
+  });
+
+  test("should return undefined when no classes provided", () => {
+    const result = cnWithMerge()({twMerge: true});
+
+    expect(result).toBeUndefined();
+  });
+
+  test("should handle arrays with tailwind-merge", () => {
+    const result = cnWithMerge(["px-2", "px-4"], "py-2")({twMerge: true});
+
+    expect(result).toBe("px-4 py-2");
+  });
+
+  test("should handle objects with tailwind-merge", () => {
+    const result = cnWithMerge({"px-2": true, "px-4": true, "py-2": true})({twMerge: true});
+
+    expect(result).toBe("px-4 py-2");
+  });
+
+  test("should merge when config is undefined (default behavior)", () => {
+    const result = cnWithMerge("px-2", "px-4")({twMerge: true});
+
+    expect(result).toBe("px-4");
+  });
+});
+
+describe.each(cxVariants)("cx function - $name", ({cx}) => {
   test("should join strings and ignore falsy values", () => {
-    expect(cn("text-xl", false && "font-bold", "text-center")).toBe("text-xl text-center");
-    expect(cn("text-xl", undefined, null, 0, "")).toBe("text-xl 0");
+    expect(cx("text-xl", false && "font-bold", "text-center")).toBe("text-xl text-center");
+    expect(cx("text-xl", undefined, null, 0, "")).toBe("text-xl 0");
   });
 
   test("should join arrays of class names", () => {
-    expect(cn(["px-4", "py-2"], "bg-blue-500")).toBe("px-4 py-2 bg-blue-500");
-    expect(cn(["px-4", false, ["hover:bg-red-500", null, "rounded-lg"]])).toBe(
+    expect(cx(["px-4", "py-2"], "bg-blue-500")).toBe("px-4 py-2 bg-blue-500");
+    expect(cx(["px-4", false, ["hover:bg-red-500", null, "rounded-lg"]])).toBe(
       "px-4 hover:bg-red-500 rounded-lg",
     );
   });
 
   test("should handle nested arrays", () => {
-    expect(cn(["px-4", ["py-2", ["bg-blue-500", ["rounded-lg", false, ["shadow-md"]]]]])).toBe(
+    expect(cx(["px-4", ["py-2", ["bg-blue-500", ["rounded-lg", false, ["shadow-md"]]]]])).toBe(
       "px-4 py-2 bg-blue-500 rounded-lg shadow-md",
     );
   });
 
   test("should join objects with truthy values as keys", () => {
-    expect(cn({"text-sm": true, "font-bold": false, "bg-green-200": 1, "m-0": 0})).toBe(
+    expect(cx({"text-sm": true, "font-bold": false, "bg-green-200": 1, "m-0": 0})).toBe(
       "text-sm bg-green-200",
     );
   });
 
   test("should handle mixed arguments correctly", () => {
     expect(
-      cn(
+      cx(
         "text-lg",
         ["px-3", {"hover:bg-yellow-300": true, "focus:outline-none": false}],
         {"rounded-md": true, "shadow-md": null},
@@ -47,15 +183,15 @@ describe.each(variants)("cn function - $name", ({cn}) => {
   });
 
   test("should handle numbers and bigint", () => {
-    expect(cn(123, "text-base", 0n, {border: true})).toBe("123 text-base 0 border");
+    expect(cx(123, "text-base", 0n, {border: true})).toBe("123 text-base 0 border");
   });
 
   test("should return undefined for no input", () => {
-    expect(cn()).toBeUndefined();
+    expect(cx()).toBeUndefined();
   });
 
   test("should return '0' for zero and ignore other falsy", () => {
-    expect(cn(false, null, undefined, "", 0)).toBe("0");
+    expect(cx(false, null, undefined, "", 0)).toBe("0");
   });
 
   test("should normalize template strings with irregular whitespace", () => {
@@ -67,10 +203,10 @@ describe.each(variants)("cn function - $name", ({cn}) => {
         rounded-lg
     `;
 
-    expect(cn(input)).toBe("px-4 py-2 bg-blue-500 rounded-lg");
+    expect(cx(input)).toBe("px-4 py-2 bg-blue-500 rounded-lg");
 
     expect(
-      cn(
+      cx(
         ` text-center
           font-semibold  `,
         ["text-sm", `   uppercase   `],
@@ -80,6 +216,15 @@ describe.each(variants)("cn function - $name", ({cn}) => {
   });
 
   test("should handle empty and falsy values correctly", () => {
-    expect(cn("", null, undefined, false, NaN, 0, "0")).toBe("0 0");
+    expect(cx("", null, undefined, false, NaN, 0, "0")).toBe("0 0");
+  });
+
+  test("should NOT merge conflicting classes (simple concatenation)", () => {
+    // cx should just concatenate, not merge
+    expect(cx("px-2", "px-4", "py-2")).toBe("px-2 px-4 py-2");
+  });
+
+  test("should handle conflicting classes without merging", () => {
+    expect(cx("text-red-500", "text-blue-500")).toBe("text-red-500 text-blue-500");
   });
 });

src/core.js

@@ -6,7 +6,7 @@ import {
   removeExtraSpaces,
   flatMergeArrays,
   joinObjects,
-  cn as cnBase,
+  cx,
 } from "./utils.js";
 import {defaultConfig} from "./config.js";
 import {state} from "./state.js";
@@ -24,7 +24,7 @@ export const getTailwindVariants = (cn) => {
 
     const config = {...defaultConfig, ...configProp};
 
-    const base = extend?.base ? cnBase(extend.base, options?.base) : options?.base;
+    const base = extend?.base ? cx(extend.base, options?.base) : options?.base;
     const variants =
       extend?.variants && !isEmptyObject(extend.variants)
         ? mergeObjects(variantsProps, extend.variants)
@@ -47,7 +47,7 @@ export const getTailwindVariants = (cn) => {
     const componentSlots = !isEmptyObject(slotProps)
       ? {
           // add "base" to the slots object
-          base: cnBase(options?.base, isExtendedSlotsEmpty && extend?.base),
+          base: cx(options?.base, isExtendedSlotsEmpty && extend?.base),
           ...slotProps,
         }
       : {};

src/index.d.ts

@@ -4,7 +4,7 @@ import type {CnOptions, CnReturn, TV} from "./types.d.ts";
 export type * from "./types.d.ts";
 
 // util function
-export declare const cnBase: <T extends CnOptions>(...classes: T) => CnReturn;
+export declare const cx: <T extends CnOptions>(...classes: T) => CnReturn;
 
 export declare const cn: <T extends CnOptions>(...classes: T) => (config?: TWMConfig) => CnReturn;
 

src/index.js

@@ -1,8 +1,8 @@
 import {getTailwindVariants} from "./core.js";
 import {cn} from "./tw-merge.js";
-import {cn as cnBase} from "./utils.js";
+import {cx} from "./utils.js";
 import {defaultConfig} from "./config.js";
 
 export const {createTV, tv} = getTailwindVariants(cn);
 
-export {cn, cnBase, defaultConfig};
+export {cn, cx, defaultConfig};

src/lite.d.ts

@@ -3,7 +3,7 @@ import type {CnOptions, CnReturn, TVLite} from "./types.d.ts";
 export type * from "./types.d.ts";
 
 // util function
-export declare const cnBase: <T extends CnOptions>(...classes: T) => CnReturn;
+export declare const cx: <T extends CnOptions>(...classes: T) => CnReturn;
 
 export declare const cn: <T extends CnOptions>(...classes: T) => CnReturn;