Server-side Tailwind class merging for Craft CMS 5

Tailwind utilities are great until two of them collide on the same element. bg-brand-accent bg-red-500 ships both classes; the cascade picks a winner and your component overrides become guesswork.

This plugin runs the merge server-side in your Twig templates. Conflicting utilities resolve last-wins per CSS property — predictably, before the HTML reaches the browser.

What you get

Twig-native merge — craft.tailwind.merge('px-4 bg-red-500', 'bg-blue-500 mt-4') returns px-4 bg-blue-500 mt-4. Accepts any number of arguments. No build step. No client JS.

Named-slot ClassList — for components with multiple style concerns (layout, color, radius, spacing, hover, focus), build classes by responsibility instead of one fragile string. Override any single slot from a parent template, leave the rest intact. Immutable — every mutation returns a new instance.

  layout: 'inline-flex items-center gap-2',
  color: 'bg-brand-accent text-white',
  radius: 'rounded-sm',
  spacing: 'py-2 px-4',
}) %}

{# Override just the color slot — layout/radius/spacing stay intact #}                                                                                                         <button class="{{ btn.override({ color: 'bg-red-600 text-white' }) }}">
  ...
</button>

Dynamic colors without safelisting — define a palette in plugin settings, render it as a <style> block of :root CSS variables, reference with arbitrary-value syntax (bg-[var(--color-brand-primary)]). Tailwind tree-shaking stops being a problem because the variable is the contract, not the class name.

Auto-detects Tailwind v3 and v4 — scans your CSS for @import "tailwindcss" / @theme directives (v4 signal), or tailwind.config.* files (v3). Routes to the correct merge engine. Override with an explicit tailwindVersion setting if detection isn't reliable for your setup.

Typography plugin support — opt-in prose-{size} and prose-{theme} conflict resolution covering @tailwindcss/typography 0.5.x suffixes, with an extras list for your own prose-* variants.

Debug toolbar panel — when devMode is on, every merge gets recorded: input, output, whether a real conflict resolved, the template that ran it, cache hit rate. Answers "why is bg-red-500 not showing up?".

Per-request LRU cache — hot class strings (your button, your card) stay resident across uses within one PHP process; size configurable, no invalidation to think about.

CSP-friendly — craft.tailwind.include({ nonce: cspNonce }) renders the injected <style> tag with whatever attributes your CSP module needs.

Requirements

• Craft CMS 5.x
• PHP 8.2+
• Tailwind CSS v3 or v4 in your buildchain

Full docs and API reference live in the GitHub README.