fix: make twMerge default to true in cn function (#283)

* fix: make twMerge default to true in cn function

* fix: make cn work directly without () and recommend cx for simple concatenation

Author: jrgarciadev

src/__tests__/cn.test.ts

@@ -24,9 +24,9 @@ describe("cn function from lite (simple concatenation)", () => {
   });
 
   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",
-    );
+    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", () => {
@@ -144,6 +144,68 @@ describe("cn function with tailwind-merge (main index)", () => {
 
     expect(result).toBe("px-4");
   });
+
+  test("should merge classes by default when called directly without ()", () => {
+    const result = cnWithMerge("px-2", "px-4", "py-2");
+
+    // Should work as a string in template literals and string coercion
+    expect(String(result)).toBe("px-4 py-2");
+    expect(`${result}`).toBe("px-4 py-2");
+  });
+
+  test("should merge classes by default when no config is provided", () => {
+    const result = cnWithMerge("px-2", "px-4", "py-2")();
+
+    expect(result).toBe("px-4 py-2");
+  });
+
+  test("should merge text color classes by default when called directly", () => {
+    const result = cnWithMerge("text-red-500", "text-blue-500");
+
+    expect(String(result)).toBe("text-blue-500");
+  });
+
+  test("should merge text color classes by default when no config is provided", () => {
+    const result = cnWithMerge("text-red-500", "text-blue-500")();
+
+    expect(result).toBe("text-blue-500");
+  });
+
+  test("should merge background color classes by default when called directly", () => {
+    const result = cnWithMerge("bg-red-500", "bg-blue-500");
+
+    expect(String(result)).toBe("bg-blue-500");
+  });
+
+  test("should merge background color classes by default when no config is provided", () => {
+    const result = cnWithMerge("bg-red-500", "bg-blue-500")();
+
+    expect(result).toBe("bg-blue-500");
+  });
+
+  test("should not merge classes when twMerge is explicitly false", () => {
+    const result = cnWithMerge("px-2", "px-4", "py-2")({twMerge: false});
+
+    expect(result).toBe("px-2 px-4 py-2");
+  });
+
+  test("should merge classes when twMerge is explicitly true (backward compatibility)", () => {
+    const result = cnWithMerge("px-2", "px-4", "py-2")({twMerge: true});
+
+    expect(result).toBe("px-4 py-2");
+  });
+
+  test("should merge classes when config is empty object (defaults to true)", () => {
+    const result = cnWithMerge("px-2", "px-4", "py-2")({});
+
+    expect(result).toBe("px-4 py-2");
+  });
+
+  test("should merge classes when config is undefined", () => {
+    const result = cnWithMerge("px-2", "px-4", "py-2")(undefined);
+
+    expect(result).toBe("px-4 py-2");
+  });
 });
 
 describe.each(cxVariants)("cx function - $name", ({cx}) => {

src/index.d.ts

@@ -3,14 +3,102 @@ import type {CnOptions, CnReturn, TV} from "./types.d.ts";
 
 export type * from "./types.d.ts";
 
-// util function
+/**
+ * Combines class names into a single string. Similar to `clsx` - simple concatenation without merging conflicting classes.
+ * @param classes - Class names to combine. Accepts strings, numbers, arrays, objects, and nested structures.
+ * @returns A space-separated string of class names, or `undefined` if no valid classes are provided
+ * @example
+ * ```ts
+ * // Simple concatenation
+ * cx('text-xl', 'font-bold') // => 'text-xl font-bold'
+ *
+ * // Handles arrays and objects
+ * cx(['px-4', 'py-2'], { 'bg-blue-500': true, 'text-white': false }) // => 'px-4 py-2 bg-blue-500'
+ *
+ * // Ignores falsy values (except 0)
+ * cx('text-xl', false && 'font-bold', null, undefined) // => 'text-xl'
+ * ```
+ */
 export declare const cx: <T extends CnOptions>(...classes: T) => CnReturn;
 
+/**
+ * Combines class names and merges conflicting Tailwind CSS classes using `tailwind-merge`.
+ * @param classes - Class names to combine (strings, arrays, objects, etc.)
+ * @returns A callable function that returns the merged class string. Works directly in template literals (coerces to string) or can be called with optional config.
+ * @example
+ * ```ts
+ * // twMerge defaults to true - works directly in template literals
+ * `${cn('bg-red-500', 'bg-blue-500')}` // => 'bg-blue-500'
+ * String(cn('bg-red-500', 'bg-blue-500')) // => 'bg-blue-500'
+ *
+ * // Can still be called with config for explicit control
+ * cn('bg-red-500', 'bg-blue-500')() // => 'bg-blue-500'
+ *
+ * // Note: If you need simple concatenation without merging, use `cx` instead:
+ * // Instead of: cn('bg-red-500', 'bg-blue-500')({ twMerge: false })
+ * // Use: cx('bg-red-500', 'bg-blue-500') // => 'bg-red-500 bg-blue-500'
+ * ```
+ */
 export declare const cn: <T extends CnOptions>(...classes: T) => (config?: TWMConfig) => CnReturn;
 
-// main function
+/**
+ * Creates a variant-aware component function with Tailwind CSS classes.
+ * Supports variants, slots, compound variants, and component composition.
+ * @example
+ * ```ts
+ * const button = tv({
+ *   base: "font-medium rounded-full",
+ *   variants: {
+ *     color: {
+ *       primary: "bg-blue-500 text-white",
+ *       secondary: "bg-purple-500 text-white",
+ *     },
+ *     size: {
+ *       sm: "text-sm px-3 py-1",
+ *       md: "text-base px-4 py-2",
+ *     },
+ *   },
+ *   defaultVariants: {
+ *     color: "primary",
+ *     size: "md",
+ *   },
+ * });
+ *
+ * button({ color: "secondary", size: "sm" }) // => 'font-medium rounded-full bg-purple-500 text-white text-sm px-3 py-1'
+ * ```
+ * @see https://www.tailwind-variants.org/docs/getting-started
+ */
 export declare const tv: TV;
 
+/**
+ * Creates a configured `tv` instance with custom default configuration.
+ * Useful when you want to set default `twMerge` or `twMergeConfig` options for all components.
+ * @param config - Configuration object with default settings for `twMerge` and `twMergeConfig`
+ * @returns A configured `tv` function that uses the provided defaults
+ * @example
+ * ```ts
+ * // Create a tv instance with twMerge disabled by default
+ * const tv = createTV({ twMerge: false });
+ *
+ * const button = tv({
+ *   base: "px-4 py-2",
+ *   variants: {
+ *     color: {
+ *       primary: "bg-blue-500",
+ *     },
+ *   },
+ * });
+ *
+ * // Can still override config per component
+ * const buttonWithMerge = tv(
+ *   {
+ *     base: "px-4 py-2",
+ *     variants: { color: { primary: "bg-blue-500" } },
+ *   },
+ *   { twMerge: true }
+ * );
+ * ```
+ */
 export declare function createTV(config: TVConfig): TV;
 
 // types

src/lite.d.ts

@@ -5,7 +5,7 @@ export type * from "./types.d.ts";
 // util function
 export declare const cx: <T extends CnOptions>(...classes: T) => CnReturn;
 
-export declare const cn: <T extends CnOptions>(...classes: T) => CnReturn;
+export declare const cn: <T extends CnOptions>(...classes: T) => (config?: any) => CnReturn;
 
 // main function
 export declare const tv: TVLite;

src/tw-merge.js

@@ -19,10 +19,10 @@ export const createTwMerge = (cachedTwMergeConfig) => {
 };
 
 export const cn = (...classnames) => {
-  return (config) => {
+  const execute = (config) => {
     const base = cx(classnames);
 
-    if (!base || !config.twMerge) return base;
+    if (!base || !(config?.twMerge ?? true)) return base;
 
     if (!state.cachedTwMerge || state.didTwMergeConfigChange) {
       state.didTwMergeConfigChange = false;
@@ -32,4 +32,39 @@ export const cn = (...classnames) => {
 
     return state.cachedTwMerge(base) || undefined;
   };
+
+  // Execute immediately with default config
+  const defaultResult = execute({});
+
+  // Create a function that can be called with config
+  const fn = (config) => execute(config);
+
+  // Make the function work as both a function and a value
+  // When used directly (e.g., in template literals), return the default result
+  // When called as a function, execute with the provided config
+  return new Proxy(fn, {
+    apply(target, thisArg, args) {
+      // Called as function: fn() or fn(config)
+      return target(...args);
+    },
+    get(target, prop) {
+      if (prop === Symbol.toPrimitive) {
+        return (hint) => {
+          if (hint === "string" || hint === "default") {
+            return defaultResult ?? "";
+          }
+
+          return defaultResult;
+        };
+      }
+      if (prop === "valueOf") {
+        return () => defaultResult;
+      }
+      if (prop === "toString") {
+        return () => String(defaultResult ?? "");
+      }
+
+      return target[prop];
+    },
+  });
 };