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.

[Nordeast]

I was able to get a setup like what you described working for me. I think the key here is that I don't have my npm library really deal with tailwind at all and have the consuming library handle the whole setup.

Here is how my vite.config.ts is configured in the npm library

import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import tailwindcss from '@tailwindcss/vite'
import * as path from 'path'

export default defineConfig({
  plugins: [vue(), tailwindcss()],
  build: {
    emptyOutDir: true,
    lib: {
      entry: path.resolve(__dirname, 'library/index.ts'),
      name: 'MyProject',
      fileName: (format) => `my-project.${format}.js`,
    },
    rollupOptions: {
      external: ['vue', 'radix-vue', 'lucide-vue-next'],
      output: {
        globals: {
          vue: 'Vue',
          'radix-vue': 'RadixVue',
          'lucide-vue-next': 'LucideVueNext',
        },
      },
    },
    outDir: 'dist',
  },
  resolve: {
    alias: {
      '@': path.resolve(__dirname, './library'),
    },
  },
})

A key part of the package.json

"exports": {
  ".": {
    "types": "./dist/index.d.ts",
    "import": "./dist/my-project.es.js",
    "require": "./dist/my-project.umd.js"
  },
  "./styles.css": "./dist/my-project.css",
  "./tailwind.preset.css": "./dist/tailwind.preset.css"
},

Then for building the library into a npm package I used a few commands:

Run your vite build and vue-tsc (if it is typescript) commands as normal
vite build && vue-tsc --declaration --emitDeclarationOnly

This should output the built library into a folder named "dist". I then just simply copy the Tailwind preset CSS file containing my @theme stuff directly into the dist folder with no modification of the source code.
cp ./library/tailwind.preset.css ./dist/tailwind.preset.css

Then I run npm pack to create the tarball
npm pack

After I have the npm package I can install in my consuming project like a normal npm package. To bring in the Vue <style> block styles and the Tailwind theme stuff I add a couple imports to the main CSS file for the consuming project.

@import 'my-project/tailwind.preset.css';
@import 'my-project/styles.css';

Then it just works. I pull in a component from the library and tailwind is able to find the classes applied to them and packages the correct CSS for me as well as I get the styles from the npm package applied to my theme.