[v4] How to tree-shake prefixed utilities in publishable component libraries?

[rosareyes]

Description

I'm developing a React component library that uses Tailwind CSS v4 (upgraded it from v3) with a custom prefix (sb:). I'm facing a critical issue where tree-shaking doesn't work when using prefixed Tailwind utilities in component libraries.

The Problem

When I build my component library with prefixed Tailwind utilities (e.g., sb:flex, sb:bg-blue-500), the generated CSS bundle includes all Tailwind utilities used across my entire library, not just the ones used in the components that consumers actually import.

Example:

• My library has 50 components
• Consumer only imports 3 components
• The CSS bundle still includes utilities from all 50 components

What I've Tried

1. Building with prefix in the library

@import 'tailwindcss' prefix(sb);

Result: CSS bundle contains all utilities from entire library (not tree-shaken)

2. Adding library as content source in consumer's app

@source  './node_modules/@stylibweb/stylib-components/**/*.{js,jsx,ts,tsx}'

Result: Tailwind doesn't detect the prefixed classes (sb:flex) because it's looking for unprefixed classes. The generated CSS doesn't include my library's styles.

None of these approaches work correctly.

Current Workaround (Not Ideal)

My current solution is to export the entire CSS bundle:

/* In consumer's app */
@import './node_modules/@stylibweb/stylib-components/dist/styles.css';

This works but has significant downsides:

• Large bundle size (includes unused CSS)
• Not optimized for production
• Defeats the purpose of utility-first CSS

Questions

1. Is there a way to make Tailwind tree-shake prefixed utilities in component libraries?

2. Can I configure the consumer's Tailwind to detect prefixed classes from node_modules?

   • Something like telling Tailwind: "scan for sb:* classes in this specific package"

3. Should I avoid using prefixes in component libraries altogether?

   • But then how do I prevent style conflicts with consumers?

4. Would a custom plugin or extractor help solve this?

Expected Behavior

I want to:

1. Use a prefix (sb:) in my library components to avoid conflicts
2. Have Tailwind generate CSS only for the utilities used in those specific components

Example Use Case

// In my library component
export const Button = ({ children }) => (
  <button className="sb:px-4 sb:py-2 sb:bg-blue-500 sb:text-white">
    {children}
  </button>
);

// In consumer's app
import { Button } from '@stylibweb/stylib-components';

// I want ONLY the CSS for sb:px-4, sb:py-2, sb:bg-blue-500, sb:text-white
// Not CSS for all other components in the library

thanks!!

[wesleysmyth]

This is an architectural challenge with how Tailwind generates CSS. The core issue: Tailwind tree-shakes by scanning source files for class names, not by analyzing runtime imports. It doesn't know which components the consumer actually uses — it just sees all class names in the content paths.

Why your current approaches fail

• Building CSS in the library with prefix(sb): Tailwind scans ALL your library source and generates CSS for every utility used. It can't know which components the consumer imports.
• @source in consumer's app: Tailwind's scanner looks for raw utility names (flex, bg-blue-500), not prefixed ones (sb:flex). The prefix is a CSS-level transform, not a source-level one.

The recommended approach: Don't bundle CSS in the library

Ship your components as JS/TSX only (no CSS bundle). Let the consumer's Tailwind process generate the CSS:

/* Consumer's CSS file */
@import 'tailwindcss' prefix(sb);
@source "../node_modules/@stylibweb/stylib-components/src/**/*.{js,jsx,ts,tsx}";

The key insight: both the library AND the consumer must use the same prefix. When the consumer configures prefix(sb), Tailwind will:

1. Scan the library source for class names like sb:flex
2. Strip the prefix to find the base utility (flex)
3. Generate the prefixed CSS output

This way, only utilities used by the imported components end up in the final CSS — true tree-shaking.

If you need the library to work standalone (with its own CSS)

You're stuck with shipping the full CSS bundle. This is a fundamental limitation: Tailwind can't know at library-build-time which components the consumer will use.

Mitigations:

• Split CSS per component: Build a separate CSS file per component, and document that consumers should import @stylibweb/stylib-components/Button/styles.css alongside the component
• Use CSS layers so the library styles don't conflict with consumer styles even without a prefix

On the prefix question

If your library is the only thing using sb: prefix, conflicts with the consumer's utilities aren't really possible anyway — Tailwind utilities are deterministic. The prefix mainly helps with non-Tailwind CSS conflicts. Consider whether you actually need it.

[rozsazoltan]

It's may interest for you:

• All components from the UI package are included in the project's generated CSS, but I don't use every component
• Adding an external source or a package from within node_modules for detection
• Shipping a UI package alongside projects in a monorepo