Best practices for distributing React component libraries with Tailwind v4 classes via npm packages

[vlorian-de]

Hi Tailwind team and community,

I'm developing a React component library that uses Tailwind CSS v4 and distribute it as an npm package.
I've encountered a common issue:
Tailwind purges the CSS classes from my compiled components when consumed in other applications, since Tailwind only scans the consuming application's source code and doesn’t "see" the classes from the precompiled library.

Current workaround

My current solution consists of:

1. Building the library using tsup
2. Auto-generating a "safelist component" that includes all Tailwind classes used across library components
3. Exporting this safelist component as uncompiled TypeScript alongside the compiled code
4. Instructing consuming apps to import this component, so Tailwind picks up the classes during its scan

// Auto-generated safelist component
export const TailwindSafelist = () => {
  return (
    <div className="hidden">
      <div className="bg-blue-500 text-white p-4 rounded-lg shadow-md hover:bg-blue-600 transition-colors" />
      {/* ...other classes used in the library */}
    </div>
  );
};

This works, but feels somewhat hacky and manual.

My questions

1. Is this an acceptable or recommended approach for library distribution with Tailwind v4?
2. Is this a common issue that library authors face when building Tailwind-based component libraries?
3. Are there any official best practices or patterns for solving this?
4. Are there any plans to improve support for library use cases like this in future Tailwind versions?

I’d greatly appreciate any input or direction on whether this approach makes sense — or if there are better alternatives I should consider.

Thanks for your time and for the amazing work on Tailwind!

Best regards
Vlorian

[rozsazoltan]

Simply add the @source directive like this to install your directory:

./css/globals.css

@import "tailwindcss";
@source "../node_modules/my-package-name/dist;

or

./css/globals.css

@import "tailwindcss";
@source "../node_modules/my-package-name/dist/**/*.{js,ts,jsx,tsx};

or just

./css/globals.css

@import "tailwindcss";
@source "../node_modules/my-package-name;

This expands the source file discovery to include not only the local project but also your UI components.

Important note: It's important not to include the entire node_modules folder in your Tailwind content paths. Instead, always specify only your own package or component directories. This way, Tailwind's engine doesn't have to scan an enormous number of files and folders unnecessarily, which can lead to performance issues or misleading "not working" reviews - when in reality, it's just running very slowly and not recommended. So use minimum /node_modules/my-package-name; and don't forget the path is relative, so it depends on the location of your main CSS file - for example, in my case, I had to go up from the ./css folder to reach the node_modules directory.

Live examples:

• HeroUI: https://www.heroui.com/docs/guide/tailwind-v4#without-tailwindconfigjs (see main css file)
• Flowbite: https://flowbite.com/docs/getting-started/quickstart/ (see Step 4)

Another:

• Or DaisyUI instead provides its own plugin that includes its custom Tailwind utilities, and developers can use the components by copying them from the documentation - https://daisyui.com/docs/install/

[vlorian-de]

Hi @rozsazoltan,
thank you so much for your quick and detailed response — your hint with the @source directive helped a lot. It not only improved the setup for our Tailwind v4-based library but also led me to the actual root cause in our case: a version mismatch.

Some consuming apps were still on Tailwind v3, which caused the classes to be purged despite our workaround. After upgrading those apps to v4, everything worked as expected — even without relying on the safelist component in some cases.

Appreciate your help and the great explanation regarding performance and path specificity — super valuable!

[vlorian-de]

Suggested answer for others running into similar issues

Thanks to @rozsazoltan’s input, I was able to solve the issue in most consuming apps. The actual problem turned out to be a mismatch in Tailwind versions — some apps still used Tailwind v3 while our component library was built with v4.

Once we upgraded those apps to Tailwind CSS v4 and used the @source directive to explicitly include the library files, the purging issue was resolved. This avoided the need for a “safelist” workaround in most cases.

If you’re running into similar problems with missing styles from a Tailwind-based component library, double-check:
• the Tailwind version in all consuming apps
• and use @source in your main CSS file to point to your library’s distribution folder.

Thanks again to the Tailwind community — especially @rozsazoltan — for the great support!