Per-source prefix control for @source (interop between prefixed apps and third-party libraries)

[kcsujeet]

The gap

In v4 the prefix set via @import "tailwindcss" prefix(tw) is global and all-or-nothing: every generated utility requires the prefix (tw:flex), and there's no way to tell Tailwind to scan a specific @source with a different prefix (or none). That makes prefixed apps and third-party Tailwind libraries hard to combine, in two mirror-image ways:

1. Consuming a library that ships unprefixed classes. A headless/render-prop library ships class="flex items-center" in its dist and asks you to @source it. Under a global prefix, only prefixed tokens generate, so none of the library's classes produce CSS and the components render unstyled:

@import "tailwindcss" prefix(tw);
@source "../node_modules/@acme/ui";   /* dist has unprefixed classes → nothing generated */

Concrete case: kcsujeet/ilamy-calendar#111

2. Consuming a library that ships prefixed classes. A library built with its own prefix (sb:flex) can't be scanned by an app looking for unprefixed tokens, and tree-shaking breaks, forcing consumers to import the library's whole prebuilt CSS. See #19684 and #19498.

Both are the same root cause: the prefix can't be scoped per source.

Why the current options don't close it

• The global prefix is the only knob; @source has no prefix parameter.
• @source inline(...) can safelist utilities, but it's unwieldy for a whole library's class set and (as far as I understand) still emits under the global prefix (confirmation welcome).
• A library can't ship dist prefixed for the consumer, because the prefix is the consumer's choice and differs per app.

Idea

A per-@source prefix control so the prefix is scoped, not global. Strawman (open to any shape that fits the design):

@import "tailwindcss" prefix(tw);

/* scan an unprefixed library as-is → generate `flex`, not `tw:flex` */
@source "../node_modules/@acme/ui" prefix(none);

/* scan a library that uses its own prefix */
@source "../node_modules/@acme/ui" prefix(sb);

This would let prefixed apps consume any Tailwind-based library without the library having to know the consumer's prefix, and would restore tree-shaking for prefixed libraries.

Related

#19645 (broader component-library ecosystem proposal, from the "each library uses its own prefix" angle), #19684, #19498, #17242. Several recurring Help threads suggest real demand.

Questions

• Is there an existing recommended pattern for this that I've missed?
• If a per-source prefix override seems reasonable, I'm happy to help prototype it.

[RobinMalfait]

Hey! I'm going to do some more research on this one. Somebody opened a PR with a solution that kind of tries to solve the same issue. I think there is a path forward where both can be used. Relevant PR: #20274

I'll come back with some research to figure out the APIs and feasibility of these feature(s).

[kcsujeet]

Thanks @RobinMalfait , appreciate you looking into it 🙏 ... Happy to help prototype or test the @source side if required.

[kcsujeet]

Hi @RobinMalfait, just checking whether there's been any progress on the research. This still blocks prefixed apps from using headless libraries that ship unprefixed classes (kcsujeet/ilamy-calendar#111 is still waiting on it). My offer stands: I'm happy to prototype the @source ... prefix(...) side, or test against #20274, if that would help.