Building reusable theme extension libraries using tailwind 4

[auirarrazaval]

In v3, it was very easy to export a reusable theme from a library using JS, import it and use it in another app. With V4 though, I haven't been able to do so as easily, as the bundling part surpasses me.
In my specific case, there's two things that I need to add to the tailwind theme: fonts and colors.

Colors is very straightforward, as I just define a set of color palettes. For this I have created the theme/colors.css file with the definitions:

@theme {
    /* Reset */
    --color-*: initial;
    /*  Basic Colors */
    --color-transparent: transparent;
    --color-black: #000000;
    --color-white: #FFFFFF;
    --color-background: #F5F5F5;

    /* Theme Colors */
   ...
}

Fonts is a bit trickier, as it adds custom font families, in two different formats:

• One comes from an npm package
• One is loaded directly from a woff file.

Therefore, my theme/fonts.css file looks something like:

@import '@fontsource/dm-sans/400.css' layer(base);
@import '@fontsource/dm-sans/500.css' layer(base);
@import '@fontsource/dm-sans/700.css' layer(base);

@font-face {
  font-family: 'Material Symbols Rounded';
  font-style: normal;
  src: url(@/fonts/MaterialSymbolsRounded.woff2) format('woff2');
}

@theme {
    --font-display: 'DM Sans', sans-serif;
    --font-body: 'Inter', sans-serif;
    --font-link: 'DM Sans', sans-serif;
    --font-symbol: 'Material Symbols Rounded', sans-serif;
}


@theme inline {
  --default-font-family: var(--font-body);
}

note that the path to the woff2 file is using the alias @. I am using vite to bundle the package and define thee alias there, so resoution works

this is the imported in an theme/index.css file:

@import './coloros.css'
@import './fonts.css'

Then, I have no issues if, in the same package, I import this folder in my tailwind entrypoint css. Something like:

@import 'tailwindcss' prefix(tw);
@import '../theme';

This works great, prefixes are added into the imported classes as expected and therefore the tailwind extension is successful

Now. I want to be able to import this in other apps that require this package. Let's say
my-app/app.css

# note, no prefix
@import 'tailwindcss' 
@import 'my-package/theme'

I would expect this to extend tailwind the same as it did inside the package itself.

What I have already managed to do:

• I am able to export css files through the package.json without many issues.
• I managed to make the colors work, by directly exporting the 'raw' css files (no bundling). It works because the color definitions of course don't require any package or import, it's pure (tailwind) css.

What fails:

Because I'm basically exporting a raw text file with a special extension, the app that imports the themee complains because it cant find the @fontsource package, or the woff2 file. And it of course makes total sense. After all, the file is being read from a context that does not have the package installed, or the font files.

What I would like to happen:
I would like to be able to bundle the extensions only, (using a css bundler maybe?) I've considered making a separate, css-only package, but I haven't been able tot find documentation on how to use tailwind 4 to bundle this correctly, as I would like the @theme ... and @theme inline directives to follow tailwinds standard. Of course, this bundled package would include the full font source.

Any guidelines? Help? References? Is anyone struggling with anything like this as well in v4?

[jwlms]

I have just stumbled upon this myself — I'll try to remember to update you when I find a solution! (Unless of course you have found one in the mean time?)

[rozsazoltan]

Related:

• https://tailwindcss.com/docs/detecting-classes-in-source-files#explicitly-registering-sources (If you're creating a component library, you don't need to include the generated CSS. Instead, make sure your library is added as a source to the current project, so each project can compile the necessary class code on its own without duplication.)
• https://tailwindcss.com/docs/theme#sharing-across-projects (Additionally, you can provide your own configuration in a CSS file - just make sure to inform the users of your library to import the appropriate CSS file from your package. They don't need to import TailwindCSS separately; just assume they will import it correctly.)

[rozsazoltan]

Additionally, you can still write JS-based plugins for TailwindCSS - this part of Tailwind is still not well documented.

• How can I pass parameters to a TailwindCSS plugin in a CSS-first configuration? #15997
• [v4] How to add plugins? #13292 (reply in thread)

[jwlms]

@rozsazoltan - Thanks for jumping in with the reply! I'm migrating an existing component library to version 4 so your reply did help (even though I had read this section of the docs: https://tailwindcss.com/docs/theme#sharing-across-projects). In case it helps others I'll outline the previous approach and how I was able to reconcile by exporting a theme.

With Tailwindcss v3 I had been relying on exporting a tailwind.config object from the library and having consumers import the config like this:

// tailwind.config.js
const theme = require('@org/component-library-styles');

module.exports = {
  content: ['./src/**/*.{ts,tsx,js,jsx}'],
  presets: [theme],
};

With Tailwindcss 4.0 the same functionality can be achieved by exporting a the theme in addition to other component-specific styles if any are required (this was my problem as I wanted everything exported in a single stylesheet, which I don't think will work with v4). So the package.json for a component library will look something like this:

{
  "name": "@org/component-library-styles",
  "version": "4.0.0",
  "exports": {
    "./main.css": "./main.css", // custom styles
    "./theme.css": "./theme.css" // the tailwinds theme
  },
}

And then the consumer's main stylesheet entry point:

@import 'tailwindcss';
@import '@org/component-library-styles/main.css'; /* optional if custom styles are needed */
@import '@org/component-library-styles/theme.css';