[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.