Production builds miss all classes from symlinked node_modules dependencies (bun + Tailwind CSS v4)

[bibblebabl]

When using bun as the package manager, arbitrary value classes from node_modules dependencies (e.g., HeroUI Native) are silently dropped in production/preview builds while working perfectly in dev.

Environment: Uniwind ^1.2.2, Tailwind CSS ^4.1.18, Bun 1.3.3, Expo ~54.0.33, HeroUI Native 1.0.0-rc.2

Root Cause

Bun stores packages via symlinks:

node_modules/heroui-native → ../../../node_modules/.bun/heroui-native@1.0.0-rc.2.../node_modules/heroui-native

The @source "./node_modules/heroui-native/src" directive tells Tailwind's Oxide scanner to scan the package. The scanner follows the symlink but there's a path mismatch in .gitignore allowlist logic — the canonical path (under .bun/.../node_modules/) gets excluded by the node_modules gitignore rule, and the allowlist doesn't match.

Arbitrary value classes (h-[56px], p-[3px], border-[1.5px], etc.) that only exist in the library source are never generated.

Why Dev Works but Production Doesn't

• Dev: Uniwind's Metro JIT plugin generates styles at runtime. Oxide scanner not involved. All classes work.
• Production: CSS is pre-compiled via the Oxide scanner. Symlinked dependency is not scanned → library-only classes missing.

Workaround

@source "./node_modules/heroui-native/src";
@source inline("h-[36px] h-[48px] h-[56px] p-[3px] -my-[3px] py-[3px] top-[3px] w-[48px] h-[24px] left-[2px] w-[28px] h-[20px] right-[2px] p-[2px] pt-[3.5px] h-[6px] w-[6px] border-[1.5px]");

Fragile — requires updating on every library upgrade.

Upstream

Tracked at tailwindlabs/tailwindcss#17985.

Possible Uniwind-level mitigations

1. Document the workaround for bun users
2. Auto-generate safelist during production builds — scan resolved dependency sources at the JS level and emit @source inline(...) transparently
3. Resolve symlinks before passing to Oxide — if Uniwind controls @source path resolution, resolve to canonical paths directly

Reproduction

1. Expo + RN project with Uniwind, bun as package manager
2. Install a library using Tailwind arbitrary values (heroui-native)
3. Add @source "./node_modules/<package>/src" to global.css
4. Build preview/production (eas build --profile preview --local)
5. Components with arbitrary classes have broken layouts
6. Compare with dev where everything renders correctly

[bibblebabl]

Scope clarification: not just arbitrary classes

After further investigation, the issue is broader than arbitrary value classes. Since the Oxide scanner can't follow bun symlinks at all, any class that exists only in the library source will be missing from production builds — not just arbitrary values.

Common utilities like flex-1, p-4, text-sm aren't affected because they're also used in app code and get picked up from there. But semantic/theme classes or less common utilities that only appear inside library components will silently disappear.

Example: theme color renames

HeroUI Native beta.13 renamed the divider theme color to separator. The library's components now use bg-separator internally. If an app doesn't happen to use bg-separator in its own code, the class won't be generated in production — even though the theme defines the color and @source points to the package.

Implication for the workaround

The current @source inline(...) workaround needs to include all library-only classes, not just arbitrary values. This makes manual maintenance even more fragile, reinforcing the need for an automated solution (option 2 or 3 in the original issue).

Updated title suggestion

"Production builds miss all classes from symlinked node_modules dependencies (bun + Tailwind CSS v4)" would better reflect the actual scope.

[divineniiquaye]

This is an issue with HeroUI Native and not Uniwind, here's my example config that fixes the issue:

@source "../../node_modules/heroui-native/lib";
@source "../../../../node_modules/heroui-native/lib";

Update the sources to your correct node_modules paths, then add this config to your .npmrc file (Tested with bun 1.3.0 up to 1.3.9):

public-hoist-pattern[]=heroui-native

Another workaround is to patch HeroUI Native and add a .css file which includes a source pointing to the lib directory, then import as eg. @import "heroui-native/styles-include-source"

[bibblebabl]

Hey, sharing what ended up working for me here.

My project was scaffolded with Better-T-Stack (Turborepo monorepo). The template's global.css already has @source './node_modules/heroui-native/lib', but in a monorepo setup bun hoists heroui-native to the root node_modules, so that relative path doesn't resolve. Might be worth updating the template for monorepo setups.

After some trial and error, the fix was just adjusting the path in global.css:

@source "../../node_modules/heroui-native/lib";

I also tried @source inline(...) with manually listed classes and even auto-generating the full class list from the library source — both worked but were super fragile and broke on every library update.

@divineniiquaye thanks for pointing toward the @source path approach, that was the key insight! Worth noting though — this isn't really a HeroUI Native issue specifically. The underlying bug is in Tailwind's Oxide scanner (tailwindlabs/tailwindcss#17985) not being able to follow bun symlinks, so it'd affect any third-party library, not just HeroUI.

Closing this out — hope it helps someone else running into the same thing!