Feat: Tailwind v4.x isn't backwards compatible for Twin.Macro

[andymerskin]

Hey there!

We got a discussion started over on Twin.Macro's repo to rally support for Tailwind v4.x. My team loves using Twin.Macro as a complete solution for mixing Tailwind with proper CSS-in-JS in our React projects.

I won't speak for @ben-rogerson, but given Twin.Macro had a healthy 15–105k+ weekly downloads over the past year, I'd guess we would start seeing more demand for v4.x support as it gains popularity and people want to start using more of its features.

With the jump to v4, it sounds like there are several APIs / utils that are no longer available or exposed by Tailwind that Twin.Macro relies on, preventing it from supporting v4 properly. There are a few still available in src/utils and src/compat, but it's unclear which ones may have moved or been renamed.

Here's where Twin.Macro imports Tailwind's utilities in v3.x:
https://github.com/ben-rogerson/twin.macro/blob/master/src/core/lib/util/twImports.ts

Brief list of named Tailwind dependencies:

toPath
resolveMatches (from generateRules)
createContext (from setupContextUtils)
stubs/config.full (default Tailwind config)
transformThemeValue
resolveConfig
getAllConfigs
splitAtTopLevelOnly

I'm going to spend some time digging around v4's code to see where these can be found (if they exist), but if any contributors more familiar with Tailwind v4 would be willing to help track these down, I'd love support! If some don't exist, what would it take to either 1) add support via src/compat to work towards backwards compatibility, or 2) find alternatives to expose what's needed?

Twin.Macro is amazing, and we don't want to let it go...

Unfortunately, moving away from Twin.Macro in an existing application is no trivial task, since it introduces useful features on top of Tailwind that it doesn't already offer, so we're hesitant to refactor our entire project to use vanilla Tailwind, since we benefit from Twin's unique features.

For anyone who hasn't tried it yet, give it a shot — it greatly eases the burden of conditional styling, variants, and mixing hand-rolled CSS with Tailwind in React / Solid / Next! 🔥

Any help would be greatly appreciated, thanks! 🙏