3.3 drops support for twMerge prefix option

[Redmega]

How do we use that now?

For example, my previous config just has:

export const tv = createTV({
  twMerge: true,
  twMergeConfig: {
    prefix: "tw",
  },
});

but this is now invalid with the latest version...

edit: I realized I probably left out some important context in the original question, we have multiple projects pulling from multiple tailwind configs/themes, so we need to be able to merge prefixed and unprefixed classes. Currently I do so by doing

function coercePrefixedClassName(className: string) {
  return className.startsWith("tw:") ? className : `tw:${className}`;
}

// ...

export const tv = createTV({
  twMerge: true,
  twMergeConfig: {
    prefix: "tw",
    experimentalParseClassName({ className, parseClassName }) {
      return parseClassName(coercePrefixedClassName(className));
    },
  }

[dgesteves]

prefix went away with the merge engine. Since 3.3.0 (#301), tailwind-variants no longer uses tailwind-merge; it ships its own resolver. TWMergeConfig now only covers the class-group part of the config (theme, classGroups, conflictingClassGroups, conflictingClassGroupModifiers, postfixLookupClassGroups, orderSensitiveModifiers, plus extend/override). That's why prefix is a type error now, and if you cast it through it's silently ignored.

For a Tailwind v4 prefix you don't need it. In v4 the prefix is a leading variant (tw:bg-red-500), and the built-in resolver treats tw like any other modifier. Classes only conflict when they have the same modifiers, so merging behaves the same. Just drop twMergeConfig:

export const tv = createTV({ twMerge: true }) // twMerge is already the default

I compared 3.3.1's cn() with tailwind-merge 3's extendTailwindMerge({ prefix: 'tw' }) and got identical output:

input	result (both)
tw:px-2 tw:px-4	tw:px-4
tw:md:px-2 tw:md:px-4	tw:md:px-4
tw:px-2 tw:md:px-4	tw:px-2 tw:md:px-4
tw:px-4 tw:p-2	tw:p-2
tw:bg-red-500 tw:hover:bg-blue-500 tw:bg-green-500	tw:hover:bg-blue-500 tw:bg-green-500
tw:[&>svg]:size-4 tw:[&>svg]:size-5	tw:[&>svg]:size-5

One difference that shouldn't matter: with prefix set, tailwind-merge treats unprefixed classes as foreign and never merges them. In a prefixed project those classes don't produce CSS anyway.

If you depend on some other tailwind-merge option the new resolver doesn't support, you can pin tailwind-variants@3.2.2. Or set twMerge: false and run the output through your own extendTailwindMerge(...) instance.

[dgesteves]

@Redmega quick follow-up: 3.3.1 is still the latest release, so this is still how it behaves. Did dropping twMergeConfig (or pinning 3.2.2) fix it for you? If so, marking the answer as accepted would help the next person who hits the type error after upgrading. If your setup relies on another tailwind-merge option, tell me which and I'll look again.

[Redmega]

I'm not sure I would consider pinning an old version a "fix" per se -- we have been unable to update tailwind-variants because of this -- but yes, the previous config continues to work as expected...

edit: I realized I probably left out some important context in the original question, we have multiple projects pulling from multiple tailwind configs/themes, so we need to be able to merge prefixed and unprefixed classes. Currently I do so by doing

function coercePrefixedClassName(className: string) {
  return className.startsWith("tw:") ? className : `tw:${className}`;
}

// ...

export const tv = createTV({
  twMerge: true,
  twMergeConfig: {
    prefix: "tw",
    experimentalParseClassName({ className, parseClassName }) {
      return parseClassName(coercePrefixedClassName(className));
    },
  }

My apologies, not sure how I missed that, it was honestly the entire reason I posted this question in the first place 😭

[dgesteves]

@Redmega thanks, that changes the answer. Merging unprefixed classes with prefixed ones is exactly the case I waved off at the end of my answer, so dropping twMergeConfig won't work for you.

3.3.1 can't do this through config. It copies prefix and experimentalParseClassName out of twMergeConfig (tw-merge.ts), but the built-in merger only applies the class-group keys (merge-configs.ts), so both are dropped. tw is then just another variant, so px-2 and tw:px-4 get different conflict keys (config-utils.ts) and both survive.

You can still upgrade. Turn off the built-in merge and run the output through your own tailwind-merge instance. 3.3.1 still lists tailwind-merge >=3.0.0 as an optional peer, so the one you already have keeps working. This replaces your current export const tv = createTV(...):

import { extendTailwindMerge } from "tailwind-merge";
import { createTV, type TV } from "tailwind-variants";

const withTw = (className: string) =>
  className.startsWith("tw:") ? className : `tw:${className}`;

const twMerge = extendTailwindMerge({
  prefix: "tw",
  experimentalParseClassName: ({ className, parseClassName }) =>
    parseClassName(withTw(className)),
});

const tvNoMerge: any = createTV({ twMerge: false });
const merge = (out?: string) => (out ? twMerge(out) : out);

export const tv = ((options: any, config: any) => {
  const component = tvNoMerge(options, config);
  const wrapped = (props?: any) => {
    const result = component(props);
    if (typeof result !== "object" || result === null) return merge(result);
    // slots: wrap each slot function
    return Object.fromEntries(
      Object.entries(result).map(([slot, fn]: [string, any]) => [
        slot,
        (slotProps?: any) => merge(fn(slotProps)),
      ]),
    );
  };
  // keep base/variants/slots metadata so `extend: button` keeps working
  return Object.assign(wrapped, component);
}) as TV;

I ran 3.2.2 with your exact config side by side with 3.3.1 plus this wrapper (tailwind-merge 3.7.0). I tried plain base/class, variants, compound variants, slots and extend, and every output matched. For example, tw:px-2 + px-4 gives px-4, and px-2 + tw:px-4 gives tw:px-4. It also type-checks against 3.3.1's types (TS 5.9). Variant props, slot names and VariantProps<typeof button> are still inferred, and the any stays inside the wrapper.

If you also import cn from tailwind-variants, call the twMerge above instead. In 3.2.2, cn picked up your createTV merge config once a component had run. In 3.3.1 it always uses the built-in merger.

The wrapper should only be temporary. The open canary PR #306 (proposed as 4.0.0) lets tailwind-variants/lite take your own merge function, and its notes point experimentalParseClassName users to exactly that. With it, the wrapper becomes:

import { createTV } from "tailwind-variants/lite";

export const tv = createTV({ twMerge }); // the extendTailwindMerge instance above

I ran the PR's preview build that way with your config and got the same output as 3.2.2. It isn't merged or released yet, and it has other breaking changes (empty results become "" instead of undefined, for one).