How to correctly publish a re-usable shared preset/config with Tailwind v4 and the Vite plugin?

[kleinfreund]

I'm working on roughly a dozen projects using a component library package that needs migrating from Tailwind 3 to 4. This process is considerably hampered by a lack of documentation on how to migrate the JavaScript configuration format to an equivalent CSS setup.

The main problem I currently face is that I can't get the consuming projects to have styles for the components that are distributed via the component library package. I was hoping to isolate the process of compiling the final stylesheets to the consuming projects, but that doesn't seem to work with the compiled components coming from the component library package.

Approach 1

In the npm package, a bunch of (compiled) Vue.js components are distributed alongside a tailwindPreset.css file that looks like this:

/* Needed in the preset to make `@reference`s work. */
@import "tailwindcss";
@plugin "@tailwindcss/typography";

@custom-variant aria-invalid (&[aria-invalid="true"]);

/*
  The default border color has changed to `currentcolor` in Tailwind CSS v4,
  so we've added these compatibility styles to make sure everything still
  looks the same as it did with Tailwind CSS v3.

  If we ever want to remove these styles, we need to add an explicit border
  color utility to any element that depends on these defaults.
*/
@layer base {
  *,
  ::after,
  ::before,
  ::backdrop,
  ::file-selector-button {
    border-color: var(--color-gray-200, currentcolor);
  }
}

@theme {
  /**
   * COLORS
   */

  --color-transparent: rgba(255, 255, 255, 0);
  /* ... */
}

In the consuming project, the main CSS file looks like this:

@import "tailwindcss";
@import "my-package/tailwindPreset";

The component library also includes components that use @apply in the Vue SFC style block with an @reference statement.

Problem

This arrangement seems more or less sensible, but the consuming project is broken. Only Tailwind classes used in the consuming project have an effect; Tailwind classes used in the components distributed via the component library package don't.

---

How does one distribute a Tailwind preset and a bunch of Vue components and have a project consume them properly using the @tailwindcss/vite Vite plugin?

[kleinfreund]

For the scenario of distributing a set of components (e.g. Vue.js components) with a build step (e.g. distributing .js bundles, not .vue files) and a Tailwind preset, these are the requirements I found to be sufficient to get a consuming project with working styles for both shared and project components.

• Include the @import "tailwindcss" statement in the shared Tailwind preset. This is necessary for @references inside the shared components to work which you'll need if they use @apply in something like Vue SFC style blocks.
• When building the distributed files, import the shared Tailwind preset in the entrypoint. This makes sure that all the necessary Tailwind styles are included in the stylesheet you're distributing. In other words, this allows the Tailwind compilation step to see them.

However, while this seemingly gets me a working version of my projects, it leads to style duplication because I effectively create one set of Tailwind styles for the library and one set for the consuming project. Commonly used utilities like grow end up being duplicated.

What's worse, this duplication leads to CSS ordering problems. Depending on what I import first and where I put the @import "tailwindcss"; statement, the project becomes hopelessly broken because CSS that would previously be in one order is now in a different one.