Config to exclude all classes which includes the -ds- string from the merging logic

[fabriciopirini]

TL;DR: Want to know how to config in order to not process any classes which includes the -ds- string.

Hi 👋

We are working with a big DS which exports the theme tokens from Figma and they are dynamically fetched and generated during build time. Currently, it has been hard to map and list all the prefixes like text-ds, bg-ds, m-ds, etc since they are quite a few and they might change in the future so not that easy to maintain.

For now, we are migrating to use tailwind-merge alongside clsx instead of the latter alone but the conflicts are wiping most of the custom classes (as expected) since we didn't config how the conflicts should be resolved.

So my question is: How can we extend the config in order to ignore all custom classes which includes -ds- and only resolve the conflicts on the Tailwind default classes?

We have tried a few approaches:

1. Establishing conflicting class groups with * or Regex but it seems like the config does not support them.

const customTwMerge = extendTailwindMerge({
  extend: {
    classGroups: {
      '*': [(value: string) => !value.includes('ds-')]
    }
  }
})

2. Overriding the class validator

const customTwMerge = extendTailwindMerge({
  override: {
    classValidator: (classGroup: string, classValue: string) => {
      if (classValue.includes('ds-')) {
        return false
      }

      return true
    }
  }
})

3. And using the experimentalParseClassName

const customTwMerge = extendTailwindMerge({
  experimentalParseClassName: ({ className, parseClassName }) => {

    if (className.includes('-ds-')) {
      return {
        baseClassName: className,
        modifiers: [],
        hasImportantModifier: false,
        maybePostfixModifierPosition: undefined
      }
    }

    return parseClassName(className)
  }
})

Any tips on how we can achieve that until we figure the config to properly resolve the conflicts?

[fabriciopirini]

Actually, I think I made it work with the following piece for now. Not sure if optional but it seems to work:

const customTwMerge = extendTailwindMerge({
  /** 
  Modifies how tailwind-merge internally compares classes for conflicts by prepending 'ignore-' to any class containing '-ds-' in its name.
  
  This ensures design system classes are grouped together during conflict resolution without affecting the actual className applied to the DOM.
  
  Example: `text-ds-badge-neutral` becomes `ignore-text-ds-badge-neutral` internally, but the original className is still applied to the component.
  **/
  experimentalParseClassName({ className, parseClassName }) {
    if (className.includes('-ds-')) {
      return {
        ...parseClassName(className),
        baseClassName: `ignore-${className}`,
      };
    }

    return parseClassName(className);
  },
});

Will leave the discussion option is case a better idea appears, otherwise, you can close it 😄

[dcastil]

Hey @fabriciopirini! 👋

Thanks for your patience! I'd also say that experimentalParseClassName is the best mechanism for that. Also modifying the beginning of the base class is smart since that will make sure that the class won't match against anything. Maybe I should add a property to the return value of experimentalParseClassName to explicitly opt out of merging, like isIgnored or so. 🤔

[dcastil]

Added an issue for that in #495.

[fabriciopirini]

Thanks @dcastil 🙌