[v4] Tailwind Not Generating Unused @theme static Utilities from a custom package

[NicolasZim]

TL;DR

Tailwind CSS, when used with @theme static, appears to not generate utilities for custom color variables that are defined but not directly used within a library (project-a). This prevents their usage in a consuming application (project-b). A workaround involving a single PostCSS instance in the consuming application (project-b) resolves the immediate issue, but the root cause might be a Tailwind (v4) behavior.

---

🚀 Stack

• React (across all projects)
• RSLib (in project-a)
• RSBuild (in project-b)
• Tailwind CSS (across all projects)
• PostCSS (across all projects)

---

🔗 Repository for Reproduction

A minimal reproduction repository is available here: https://github.com/NicolasZim/poc-tailwind-rslib-issue

---

📝 Issue Description

project-a is a library that defines custom colors within its Tailwind theme. The goal is to expose these custom colors as utilities for consumption by another project, project-b.

The problem arises when project-a is built: Tailwind does not seem to generate utilities for custom color variables that are defined in @theme static but are not directly "used" within project-a's own codebase.

According to my understanding, using @theme static should instruct Tailwind to generate all specified utilities regardless of their usage for static analysis. However, if I define ten custom colors in project-a's theme but only use five of them within project-a itself, the remaining five are not present in the generated CSS and thus cannot be used by project-b. This suggests that Tailwind's "smart usage recognition" might be overly aggressive or misinterpreting the static directive in this cross-project scenario.

If you inspect the provided reproduction repository, you'll observe that custom colors prefixed with custom-teal-XXX are defined but not used in project-a/theme/theme.css. Consequently, they are not available for IntelliSense or application in App.tsx within project-b, despite project-b importing project-a's compiled CSS.

---

💻 Code Samples (from poc-tailwind-rslib-issue repo)

project-a/theme/theme.css

@import "tailwindcss";

@theme static {
	--color-al-teal-10: #eaeeee;
	--color-al-teal-25: #cad4d5;
	--color-al-teal-75: #607d81;
	--color-al-teal-100: #2b5257;

	--color-custom-teal-10: #eaeeee;
	--color-custom-teal-25: #cad4d5;
	--color-custom-teal-75: #607d81;
	--color-custom-teal-100: #2b5257;
}

Expected behavior: The custom-teal-XXX colors should generate corresponding Tailwind utilities, regardless of whether they are used in project-a.
Actual behavior: These utilities are not generated.

project-b/global.css

@import "tailwindcss";
@import "../node_modules/project-a/dist/theme/global.css";
@source "../node_modules/project-a/dist/**/*.{ts,tsx}";

---

🧪 Things I've Tried

• Removing static from @theme: This was tested to see if the static keyword was somehow interfering, but it did not resolve the issue.
• Removing PostCSS from project-a: This is the current workaround that allows the utilities to be generated correctly in project-b.
• Setting up different configurations in RSLib, RSBuild, or alternative CSS import methods: Various attempts were made to adjust build configurations within RSLib and RSBuild, as well as experimenting with different ways of importing CSS files, but none yielded the desired outcome.
• Testing different variable names: I considered the possibility of naming conflicts or reserved namespaces and tried different variable naming conventions, but the problem persisted.
• Using only one global.css file in project-a: In the case that the issues was related to imports.

---

✅ Current Workaround

A temporary solution that was identified (with help from the RSLib Discord channel) involves removing PostCSS from project-a's build process and instead running a single PostCSS instance solely within project-b. This effectively defers the Tailwind transformation to the consuming application, where it seems to correctly process all defined custom variables.

While this workaround addresses the immediate problem, I am still evaluating if it has other implications for other workflows and scenarios within a larger codebase.

---

🚧 Important Constraint

In our real-world application, project-b cannot directly access the source files of project-a. It can only consume the compiled output (i.e., the dist folder) of project-a. This constraint makes the current behavior of Tailwind particularly problematic.

---

🤔 Potential Questions for Discussion

• Is this an expected behavior when using @theme static in a library context, or is it a bug in Tailwind CSS's (v4) compilation?
• Are there alternative approaches or configurations to ensure that all @theme static variables generate utilities, even if unused in the defining project, while respecting the dist-only consumption constraint?

---

[dzedajj]

@NicolasZim

Has this been fixed? Is there a better workaround for this? Having the exact same issue, but implemented another workaround using @source inline where I have to manually add every class that I want to use.

@source inline("bg-background");

[NicolasZim]

Not that I'm aware of, I just accepted the current state of the problem and made copies of the file across projects since (in my case) is a very small easy to maintain file.
The other option I have found is in here: https://github.com/NicolasZim/poc-tailwind-rslib-issue (already mentioned in the post itself).

I'm really sorry, I would really like this to be fixed too but I don't know what else to do, have done this post as suggested by the RSLib dev's from discord.

[wongjn]

You'd want to @import the source CSS of project-a into project-b.

In project-a, retain src/theme/theme.css:

--- a/packages/project-a/package.json
+++ b/packages/project-a/package.json
@@ -19,7 +19,8 @@
 	},
 	"types": "./dist/index.d.ts",
 	"files": [
-		"dist"
+		"dist",
+		"src/theme/theme.css"
 	],
 	"scripts": {
 		"build": "rslib build",

Remove the @import "tailwindcss" in theme.css to avoid duplicate CSS when project-b consumes it:

--- a/packages/project-a/src/theme/theme.css
+++ b/packages/project-a/src/theme/theme.css
@@ -1,5 +1,3 @@
-@import "tailwindcss";
-
 @theme static {
 	--color-al-teal-10: #eaeeee;
 	--color-al-teal-25: #cad4d5;

Change the @import in project-b to point to src/theme/theme.css:

--- a/packages/project-b/src/global.css
+++ b/packages/project-b/src/global.css
@@ -1,3 +1,3 @@
 @import "tailwindcss";
-@import "../node_modules/project-a/dist/theme/global.css";
+@import "../node_modules/project-a/src/theme/theme.css";
 @source "../node_modules/project-a/dist/**/*.{ts,tsx}";

[NicolasZim]

Your suggestion does fix the issue. Thanks for that! However, the docs do not explicitly show that, neither does it explain that the @import "tailwindcss" would duplicate the CSS itself, my POV was that it would tell tailwind that the file contained it's configuration (on top of importing utilities, components. ...), but I guess you could argue that if you are using tailwind all .css files would contain them, even if not, you could use source not or @import ... source().

Also: You did not explicitly say if is correct to use postcss in project-a, which I assume not for the reason of building the tailwind only where it's necessary, aka, in a project that is going to be hosted, would that be correct?

[wongjn]

You wouldn't necessarily need PostCSS in the library project.

[ahsath]

same issue, had to use @source inline(...) for each utility class not generated when using @theme static which does nothing and it is pretty much the same as using @theme inline or just plain @theme

[rozsazoltan]

The static option forcefully adds the variables to the generated CSS.
For example, --color-green-500 is not part of the generated CSS by default (neither is the variable itself) until you use at least one related utility somewhere in your inline HTML, JSX, TSX, Vue, or other files - e.g. text-green-500.
At that point, both text-green-500 and --color-green-500 become part of the generated CSS.

If you declare the color in a static theme, the difference is that --color-green-500 will always be part of the generated CSS, but the utilities themselves won't - imagine how huge your generated CSS would become if it contained all the unnecessary utilities like text-green-500, bg-green-500, border-green-500, sm:text-green-500, md:text-green-500, etc. - that's a lot.

• Static theme variables

Utilities are only added to the generated CSS when you actually use them.
If you want to dynamically set, for example, a background or text color, you should add the variables to the generated CSS using static, and then reference them dynamically with something like bg-(--variable-name). You can read more about that here:

• How do you reference dynamic classes/utilities using a JS variable and pass them through in the class attribute inline in HTML?
• How to build dynamically class names with Tailwind CSS

Your safelist solution works because it forcefully generates the utilities regardless of usage. However, use it carefully - you can easily bloat your generated CSS unnecessarily, increasing your server's bandwidth usage.

• How is it possible to specify a safelist in TailwindCSS v4? Is it possible to list patterns and variants instead of full class names?

[ahsath]

i see, i might have misunderstood how theme static works, the docs gave me the impression that utilities classes will be generated regardless not CSS variables, good to know, thanks