Skip to main content

​
Overview

When working with monorepos or shared component libraries, you may need to include source files from outside your main application directory. Uniwind leverages Tailwind CSS v4’s automatic content detection, which intelligently scans your project for class names without manual configuration.
Not using a monorepo? This guide also applies to standard projects! If your global.css is in a nested folder (like app/global.css for Expo Router) and you have components in other directories, you’ll need to use @source to include them.
Tailwind v4 automatically excludes files listed in .gitignore and binary file types, so you don’t need to worry about scanning node_modules or generated files.

​
Including External Sources

If you’re using shared UI components from other packages in your monorepo, you can explicitly include them using the @source directive in your global.css file.

​
Using the @source Directive

Add the @source directive to your CSS entry file to include additional directories:
global.css
@import 'tailwindcss';
@import 'uniwind';

@source '../packages/ui-components';
@source '../packages/shared-components';
The @source directive uses the same smart detection rules as automatic scanning, so it will skip binary files and respect .gitignore entries.

​
Common Use Cases

​
Expo Router with Components Outside App Directory

If you’re using Expo Router and your global.css is in the app directory, but you have components in a separate components folder:
app/global.css
@import 'tailwindcss';
@import 'uniwind';

/* Include components directory at the root level */
@source '../components';
This is a common setup for Expo Router projects where routes live in app but shared components live in components.

​
Shared Component Library

If your monorepo has a shared UI library that other apps consume:
global.css
@import 'tailwindcss';
@import 'uniwind';

/* Include your shared component library */
@source '../../packages/ui-library';

​
Multiple Package Sources

For complex monorepos with multiple component packages:
global.css
@import 'tailwindcss';
@import 'uniwind';

@source '../packages/design-system';
@source '../packages/feature-components';
@source '../packages/marketing-components';

​
Third-Party UI Libraries

Include custom UI libraries from node_modules that aren’t automatically detected:
global.css
@import 'tailwindcss';
@import 'uniwind';

@source '../node_modules/@my-company/ui-kit';

​
How Automatic Detection Works

Tailwind v4 (and by extension, Uniwind) automatically discovers template files in your project using intelligent heuristics:
  1. Respects .gitignore - Files in .gitignore are automatically excluded
  2. Skips binary files - Images, videos, archives, and other binary formats are ignored
  3. Scans relevant files - Focuses on source files where className attributes are likely to appear
Important: The cssEntryFile path in your metro.config.js determines the app root. Tailwind scans for classNames starting from the directory containing your global.css file. Files outside this directory require the @source directive.
In most cases, you won’t need to configure anything. Automatic detection works out of the box for standard project structures.

​
When to Use @source

You typically only need the @source directive when:
  • Your global.css is in a nested folder and you have components in sibling or parent directories (common with Expo Router)
  • Using shared components from other packages in a monorepo
  • Consuming a custom UI library that’s outside your main app directory
  • Working with Yarn/pnpm workspaces where packages are symlinked
  • Including components from a private npm package that contains Uniwind classes
If your components are already within your app directory or workspace, you don’t need @source - automatic detection handles it.

​
Troubleshooting

​
Classes Not Being Detected

If classes from your shared library or components aren’t being detected:
  1. Check your cssEntryFile path in metro.config.js - make sure it points to the correct global.css location
  2. Verify the path in your @source directive is correct and relative to your global.css file
  3. Check that the files aren’t excluded by .gitignore
  4. Ensure the source directories contain actual source files, not just compiled JavaScript
  5. Restart your Metro bundler after adding @source directives

​
Performance Concerns

If build times increase after adding @source:
  • Make sure you’re not accidentally including large directories like node_modules
  • Verify your .gitignore is properly configured to exclude build artifacts
  • Only include specific package directories rather than entire workspace roots

Quickstart

Set up Uniwind in your React Native project

Global CSS

Learn more about configuring your global.css file

Metro Config

Configure Metro bundler for Uniwind