Configure Tailwind v4 with Angular in an Nx Monorepo

Tailwind CSS v4 brought significant simplifications: no more tailwind.config.js, minimal dependencies, and a simple CSS import to get started. But if you're using Angular with Tailwind v4 in an Nx monorepo, there's a catch: your production CSS might be larger than it needs to be.

This article explains how Tailwind v4's scanning works with Angular's PostCSS setup, why it can lead to bloated CSS output, and how to optimize it using @source directives and Nx Sync Generators.

Setting Up Tailwind v4 with Angular

Setting up Tailwind v4 with Angular is straightforward. Both the Angular docs and Tailwind docs have guides for this. But they miss one important aspect when working in a monorepo, which is what we're digging into today.

Since Angular uses PostCSS for CSS processing, you need the PostCSS plugin.

Install the required packages:

Configure PostCSS in your application:

Import Tailwind in your styles entry point:

That's it. Your Angular app now has Tailwind v4 configured. But here's where things get interesting in a monorepo setup.

The Problem: Over-Scanning in Monorepos

Consider a typical Nx workspace structure:

When you run nx build demoapp, you'd expect only the Tailwind classes from demoapp and its dependency ui-design-system to end up in the final CSS. But that's not what happens by default.

Let's say another-ui has a component with this template:

Even though demoapp never imports another-ui, if you check your production CSS output, you'll find text-red-500 in there. This happens for every unused class in every library in your workspace.

Why Does This Happen?

The @tailwindcss/postcss plugin uses process.cwd() as its default scanning base:

When you run nx build demoapp, process.cwd() is your workspace root. Tailwind scans from there, finding all .html, .ts, and other template files across your entire monorepo.

This is different from the @tailwindcss/vite plugin, which uses the Vite config root (typically the app directory) as its base. With Vite you have the opposite problem: not enough is included by default, so you must explicitly add library sources. If you're using Vite with React or other frameworks, check out the Tailwind v4 with Vite in an NPM Workspace guide.

You could restrict the scanning by providing the base property in your PostCSS config:

But then you'd need to manually add @source directives for all your library dependencies. We'll look at a more automated approach.

Comparing PostCSS vs Vite Plugin Behavior

With the PostCSS plugin, you get all classes from all libraries. With the Vite plugin, you get only classes from the app and must explicitly add library sources. Both approaches benefit from automation to manage @source directives.

Solution: Restricting Scanning with @source Directives

Tailwind v4 provides the source() function and @source directive to control which directories get scanned.

Step 1: Restrict Automatic Scanning

Update your styles entry point to limit automatic scanning to just your app:

The source("./app") modifier tells Tailwind to only auto-scan the app subdirectory relative to this CSS file.

Step 2: Add Library Dependencies

Now you need to explicitly add your library dependencies:

With this configuration:

• Classes from apps/demoapp/src/app/** are included (via source("./app"))
• Classes from libs/ui-design-system/src/** are included (via @source)
• Classes from libs/another-ui/** are NOT included

Your production CSS now contains only what you actually use.

Automating @source with Nx Sync Generators

Manually maintaining @source directives works, but introduces maintenance burden:

• Easy to forget when adding new dependencies
• Missing styles don't break builds (just cause visual bugs)
• Every team member needs to remember to update paths

Nx Sync Generators solve this by automatically keeping your @source directives in sync with your project dependencies.

Using @juristr/nx-tailwind-sync

In the Tailwind v4 with Vite in an NPM Workspace article, I explained how to build a custom sync generator to automate @source directive management. I've since packaged this into @juristr/nx-tailwind-sync so you can use it directly.

Install it:

Register the sync generator in your application's project.json:

Now when you run nx build demoapp or nx serve demoapp, the sync generator:

1. Analyzes your application's dependency graph
2. Generates @source directives for each dependency
3. Updates your styles.css automatically

Your styles file gets managed markers:

When you add a new library dependency, the next build or serve detects the change and updates the directives automatically.

How Sync Generators Work

Sync generators run before certain targets (like build or serve) and check if generated files are in sync with your source code. If something is out of sync, Nx prompts you to apply the changes.

This is the same mechanism Nx uses to keep TypeScript project references in sync with your dependency graph. Learn more in the Sync Generators documentation.

Alternative: PostCSS Plugin Approach

Community member Poul Hansen created a PostCSS plugin that achieves similar automation at build time rather than through sync generators.

This approach uses the createGlobPatternsForDependencies function from @nx/angular/tailwind to dynamically inject sources during the PostCSS processing phase. Check out the gist for implementation details.

Conclusion

Tailwind v4's simplified setup is great for standalone projects, but requires attention in monorepos. With Angular's PostCSS-based setup, the default behavior scans your entire workspace, potentially bloating your production CSS with unused classes.

By combining source() restrictions with @source directives and automating their maintenance through Nx Sync Generators, you get optimal CSS output without manual upkeep.

Learn More

• Nx Docs
• Tailwind v4 with Vite in an NPM Workspace
• @juristr/nx-tailwind-sync on npm
• Nx Sync Generators Documentation
• Tailwind CSS: Detecting Classes in Source Files
• Nx YouTube Channel