Safely merge CSS output from two TailwindCSS builds without prefix

[sentience]

TL;DR: It would be useful to be able to merge the output of two or more Tailwind builds safely, avoiding source-order issues. Might this be added either to Tailwind (as a new @ rule), or as a separate PostCSS plug-in?

In detail

We use TailwindCSS to:

• style our design system shared components, which we distribute as an NPM package containing JavaScript and pre-compiled CSS
• style the apps that use those design system components for common UI elements

As a result, we have the CSS output of two TailwindCSS builds coexisting in a single page. Ideally, we would like to maintain a single TailwindCSS configuration, so that our engineers can use the same utility class names regardless of whether they're working on a shared component or an application codebase.

Unfortunately, two identically-configured TailwindCSS builds cannot currently coexist on the same page safely, because Tailwind's CSS output depends on source order (e.g. shorthand properties like m-0 are generated before non-shorthand properties like ms-4). Here's an example of the kind of source-order problem you encounter when you load two Tailwind stylesheets on the same page:

<div class="m-0">This is my application.</div>
<div class="m-0 ms-4">This is a shared component</div>

/* shared component styles */
.m-0 {
  margin: 0px;
}
.ms-4 {
  margin-inline-start: 1rem;
}
/* application styles */
.m-0 {
  margin: 0px; /* ❌ overides .ms-4 */
}

Currently, the only way to resolve this is to configure one or both of the two Tailwind builds with a prefix. For example, you might configure your component library with a prefix of 'lib-':

<div class="m-0">This is my application.</div>
<div class="lib-m-0 lib-ms-4">This is a shared component</div>

/* shared component styles */
.lib-m-0 {
  margin: 0px;
}
.lib-ms-4 {
  margin-inline-start: 1rem;
}
/* application styles */
.m-0 {
  margin: 0px;
}

As mentioned above, this is non-ideal because engineers need to context-switch depending on whether they are working in the shared component codebase or the application codebase.

I have written this use case up in greater detail on my blog, here: Use TailwindCSS prefixes for shared design system components

Proposal

A typical TailwindCSS stylesheet is written like this:

@tailwind base;
@tailwind components;
@tailwind utilities;

When we attempt to pull in the CSS file for a component library, it looks like this:

@import "component-library/styles.css";
@tailwind base;
@tailwind components;
@tailwind utilities;

What if we could do this:

@tailwindImport "component-library/styles.css";
@tailwind base;
@tailwind components;
@tailwind utilities;

@tailwindImport could parse the provided CSS file for Tailwind selectors matching the current build's configuration, and add them to this build's safelist (i.e. the list of utilities that will be generated even if they don't appear in the project source code). The output resulting from the following three @tailwind directives would therefore be a safe merge of the styles used by the component library and the styles used by the current application.

Alternatively, I could imagine this implemented as a separate postcss plug-in, which would retrospectively de-dupe and reorder Tailwind styles found in a stylesheet containing multiple Tailwind build outputs, given the Tailwind config of those builds:

export default {
  plugins: {
    tailwindcss: { config: "tailwind.config.js" },
    "tailwindcss-safe-merge": { config: "tailwind.config.js" }
  }
}

This feels harder to implement than the above @tailwindImport suggestion, though.

[mello-r]

I also stumbled upon the source order problem. I found another possible solution. You can include the Package in the tailwind.config.js under content and not import the package's CSS file. For example

// tailwind.config.js
export default {
  content: [
    './node_modules/frontend-lib/dist/**/*.{js,mjs,jsx,ts,tsx}',
    './src/**/*.{js,mjs,jsx,ts,tsx}',
  ],
}

This will also include the styles of the frontend-lib package in the output CSS file.