Part 3: Structuring Large Angular Monorepos for Performance

When you first start using an Nx monorepo for Angular, it can feel like a game-changer. Imagine a single repository where all your applications and libraries coexist, sharing tools, a dependency graph, and code generators that enforce consistency across the board. It's a developer's dream.

However, as your project and team scale, a disorganized workspace can quickly turn into a nightmare. You'll notice builds slowing down, pesky circular dependencies popping up, and different teams getting in each other's way. I've witnessed firsthand how a monorepo that started as a productivity boon can become a major bottleneck.

The key to preventing this isn't just better tools; it's thoughtful architectural design. In this article, we'll explore how to structure large Angular monorepos for peak performance, use Nx to enforce clear boundaries between different parts of your codebase, and apply proven design patterns to keep your workspace healthy and scalable.

Why Workspace Structure is Crucial

Think of your monorepo like a growing city. Initially, you can place buildings (apps and libraries) wherever you want without issue. But as the population of developers grows, you'll start seeing traffic jams (dependency chaos) and power outages (build failures). A well-structured Nx workspace is essential for:

• Clarity 🗺️: Developers can easily find where code lives and understand how different pieces connect.
• Boundaries 🚧: Teams are prevented from creating hidden dependencies that can slow down builds.
• Performance ⚡: Builds can scale predictably thanks to caching and parallelization.
• Maintainability 🛠️: Refactoring code feels less like defusing a bomb and more like a controlled process.

These aren't just best practices; they're fundamental principles that apply whether you're building a simple single-page app or a complex monorepo with dozens of applications.

The Standard Nx Folder Structure

Nx suggests a straightforward top-level structure to get you started:

apps/
  shop/
  admin/
libs/
  shared/
  ui/
  feature/
tools/
nx.json
workspace.json
tsconfig.base.json

This is the standard Nx folder structure. At a glance, it seems simple enough. But the key to performance and long-term scalability lies in how you organize the libs/ folder.

Domain-Driven Design in Nx

One of the most effective patterns for structuring a large monorepo is Domain-Driven Design (DDD). Instead of throwing everything into broad, generic folders like shared/ or ui/, you organize libraries by their business purpose.

For example, a better libs/ structure might look like this:

libs/
  feature/
    checkout/
    orders/
  shared/
    ui/
    auth/
  data-access/
    products/
    customers/

• Feature libraries contain business-specific features (checkout, orders).
• Shared libraries hold reusable components and services that are used across multiple features.
• Data-access libraries handle all API communication for a specific domain.

This layered approach creates clear boundaries and prevents the creation of "god libraries" that everything depends on. It also ensures a clean flow of dependencies:

[ apps/ ] → depend on → [ feature libs ]
[ feature libs ] → depend on → [ data-access + shared libs ]
[ shared libs ] → reusable across all

This layered model ensures that dependencies always flow downward, never sideways or upward.

Enforcing Boundaries with Nx

Even the best structure can fall apart if developers don't adhere to it. That's where Nx's dependency constraints come in. You can use tags in your nx.json file to define what can depend on what.

{
  "projects": {
    "checkout": { "tags": ["type:feature", "scope:checkout"] },
    "auth": { "tags": ["type:shared", "scope:auth"] },
    "products-data": { "tags": ["type:data-access", "scope:products"] }
  },
  "implicitDependencies": {},
  "targetDependencies": {},
  "workspaceLayout": { "appsDir": "apps", "libsDir": "libs" }
}

Then, you enforce these rules with the @nx/enforce-module-boundaries ESLint rule in your .eslintrc.json file:

"overrides": [
  {
    "files": ["*.ts"],
    "rules": {
      "@nrwl/nx/enforce-module-boundaries": [
        "error",
        {
          "depConstraints": [
            { "sourceTag": "type:feature", "onlyDependOnLibsWithTags": ["type:data-access", "type:shared"] },
            { "sourceTag": "type:shared", "onlyDependOnLibsWithTags": ["type:shared"] }
          ]
        }
      ]
    }
  }
]

With this setup, if a developer in a feature library tries to import code from another feature library, Nx will immediately throw an error during linting.

Breaking Down Large Libraries

A common mistake in large monorepos is creating bloated libraries. For instance, putting every component into a single libs/shared/ui/ library. Over time, this becomes a monster that every app depends on.

Why it hurts performance:

• A small change in shared/ui invalidates the cache for all apps that depend on it.
• Builds and tests get slower as the dependency graph grows.

The fix: Split large libraries into more focused ones. Instead of one massive ui library, you can have:

libs/shared/
  ui-buttons/
  ui-forms/
  ui-layout/

Now, when a form component changes, only the apps that actually use the ui-forms library need to be rebuilt. This simple change can shave minutes off build times in a large repository.

The Silent Killer: Circular Dependencies

Nothing damages build performance and maintainability quite like circular dependencies.

For example, if feature-checkout depends on shared-auth, which depends on feature-orders, which then depends back on feature-checkout—you have a loop. This confuses the dependency graph and forces unnecessary rebuilds.

How to detect them: Use the nx dep-graph command. This will open a visual representation of your workspace's dependencies in the browser, where you can easily spot and fix any red circles indicating a cycle.

The fix: Refactor the shared logic into smaller, dedicated libraries. In the example above, you could extract the common authentication utilities from the feature libraries and place them in libs/shared/auth.

CI/CD with a Structured Workspace

A well-structured monorepo is the foundation for an efficient CI/CD pipeline.

• nx affected:build will only rebuild the applications and libraries that have been impacted by a recent pull request.
• Caching allows you to reuse build artifacts from previous runs, skipping redundant work.
• Parallelization enables you to build and test multiple libraries at the same time.

With clean boundaries and smaller, focused libraries, affected builds become much faster and more predictable.

Final Thoughts

While Nx makes it easy to get started, structuring your monorepo for performance is a continuous effort. A good workspace design determines how much work your build process needs to do in the first place.

• Design libraries around domains, not convenience to prevent bloated "god" libraries.
• Enforce module boundaries with tags to keep your team honest and maintain a clean structure.
• Break down large libraries early to ensure faster builds and more manageable code.
• Regularly check for circular dependencies and refactor when you find them.

If caching helps you avoid wasted work, a smart workspace design determines how little work you have to do in the first place. This discipline is the key to a productive, scalable monorepo.