DEV Community: Sakthikumaran Navakumar

Angular Schematics Deep Dive — Part 1: Understanding the Architecture

Sakthikumaran Navakumar — Mon, 09 Mar 2026 02:53:25 +0000

This is Part 1 of a 6-part series on Angular Schematics. The complete roadmap is listed at the end of this article. Future parts cover custom generators (ng generate), installation schematics (ng add), migration schematics (ng update), testing with Angular DevKit, and advanced patterns including Nx integration.

Every time you run ng generate component, ng add @angular/material, or ng update, something remarkably sophisticated is happening beneath the surface. Angular's CLI isn't simply copying template files — it is executing a structured, transactional, and fully testable code transformation pipeline. That pipeline is powered by Angular Schematics.

For many Angular developers, schematics remain a black box — something the framework uses internally, something Nx and Angular Material ship with, something you might glance at and walk away from. That's a missed opportunity. Understanding schematics is the difference between a developer who uses Angular tooling and one who extends it.

In this first article, we pull back the curtain completely. We'll examine the conceptual model, the runtime architecture, the four core abstractions, the virtual file system, and the execution pipeline that every schematic runs through. By the end, you'll have a precise mental model of how schematics work — which is the essential prerequisite for building your own.

What Exactly Is a Schematic?
How the Angular CLI Uses Schematics
Architecture Overview — The Four Pillars
The Schematic Execution Pipeline
Exploring the Built-in Schematics Collection
When to Create Custom Schematics
Summary & What's Next

What Exactly Is a Schematic?

At its core, a schematic is a pure function that describes file system transformations. It receives a representation of the file system as input and returns a description of how that file system should change — without directly touching disk until all transformations are validated and committed.

That definition contains three ideas worth unpacking carefully.

1. It's a pure function. Schematics follow functional programming principles. A schematic doesn't mutate the world directly. It receives state, produces a new description of state, and hands that description off to a runner.

2. It describes transformations — it doesn't execute them. Creating a file in a schematic isn't the same as calling fs.writeFileSync(). You're building a description of what should happen, giving the framework an opportunity to validate, preview, and batch everything before committing.

3. It operates on a virtual file system. The file system schematics work with is an in-memory representation. This is what makes dry-run mode, transactional rollbacks, and unit testing possible and practical.

💡 A useful mental model: Think of a schematic the way a database thinks of a transaction. You open a transaction (the virtual Tree), describe all your changes (Rules), and then either commit them all atomically or roll back entirely. No partial states, no corrupted workspaces.

How the Angular CLI Uses Schematics

Angular CLI commands map directly to schematics. When you run any of the following, you are invoking a schematic from a registered collection:

# Invokes the 'component' schematic from @schematics/angular
ng generate component my-feature

# Invokes the 'ng-add' schematic from @angular/material's package.json
ng add @angular/material

# Invokes migration schematics listed in the package's migrations.json
ng update @angular/core

This mapping is not magic — it's configuration. Every Angular library that participates in this ecosystem declares its schematics in package.json through two fields:

Field	Purpose	Example Value
`"schematics"`	Path to collection.json for ng generate / ng add	`"./schematics/collection.json"`
`"ng-update"`	Points to migrations.json for ng update	`{"migrations": "./migrations.json"}`

The collection.json acts as a manifest — a registry of all named schematics the package exposes, the TypeScript factory function for each, and the JSON schema that defines the schematic's options. The CLI reads this manifest, resolves the factory, and hands it to the DevKit runtime.

Architecture Overview — The Four Pillars

The Angular DevKit (@angular-devkit/schematics) is built around four foundational abstractions. Understanding each one precisely is the prerequisite for writing effective schematics.

1. Tree — The Virtual File System

The Tree is the representation of the workspace as the schematic sees it. It is an immutable snapshot combined with a staged layer of mutations that haven't been applied yet. When you call tree.create() or tree.overwrite(), you are adding entries to that staging layer — not touching disk.

import { Tree } from '@angular-devkit/schematics';

export function mySchematic(options: MyOptions) {
  return (tree: Tree) => {
    // READ — returns buffer or null (no I/O hits disk)
    const content = tree.read('angular.json');

    // WRITE — stages a change, does NOT write to disk
    tree.create('src/my-file.ts', 'export const x = 42;');

    // OVERWRITE — also staged, not committed yet
    tree.overwrite('src/app/app.module.ts', updatedContent);

    return tree; // return the mutated tree
  };
}

The Tree also exposes tree.exists(), tree.delete(), tree.rename(), and tree.getDir() for directory traversal. Everything is synchronous and backed by in-memory buffers unless you are reading a file that only exists on disk and hasn't been modified yet.

2. Rule — The Unit of Work

A Rule is the atomic unit of transformation in schematics. Its type signature is elegantly simple:

// From @angular-devkit/schematics internals
type Rule = (tree: Tree, context: SchematicContext)
  => Tree | Observable<Tree> | Rule | void;

Rules are composable. The DevKit provides chain() to compose multiple rules sequentially, branchAndMerge() to run rules on a branched copy of the Tree, and mergeWith() to merge a generated file source into the existing Tree. This composability is what makes schematics architecturally powerful — complex operations are built from simple, independently testable pieces.

import { Rule, chain, mergeWith, apply, url }
  from '@angular-devkit/schematics';

export function myFeature(options: Schema): Rule {
  return chain([
    addFilesFromTemplates(options),  // Rule 1
    updateAngularJson(options),      // Rule 2
    addImportToAppModule(options),   // Rule 3
  ]);
}

3. Source — Generating a New Tree

A Source is a factory that produces an entirely new, empty Tree from some origin — typically a directory of template files. The most commonly used Source is url(), which reads template files from a local directory. Sources are merged into the main Tree using mergeWith().

import { apply, url, applyTemplates, move, mergeWith }
  from '@angular-devkit/schematics';
import { strings } from '@angular-devkit/core';

const templateSource = apply(url('./files'), [
  applyTemplates({
    name: options.name,
    dasherize: strings.dasherize,
    classify: strings.classify,
  }),
  move(options.path),
]);

return mergeWith(templateSource);

4. SchematicContext — Runtime Information

The SchematicContext is passed alongside the Tree into every Rule. It provides access to the logger (use this instead of console.log), task scheduling (for running npm install after file generation), and the engine executing the schematic. It's the schematic's connection to the outside world.

import { SchematicContext, NodePackageInstallTask }
  from '@angular-devkit/schematics';

(tree: Tree, context: SchematicContext) => {
  context.logger.info('Installing dependencies...');

  // Schedule npm install to run AFTER all file mutations commit
  context.addTask(new NodePackageInstallTask());

  return tree;
};

The Schematic Execution Pipeline

With the four pillars understood, let's trace the full lifecycle of a schematic execution from CLI command to committed files.

CLI Command
───────────
ng generate component dashboard

     │
     ▼
CLI resolves collection
─────────────────────────
Reads package.json → "schematics": "./schematics/collection.json"
Reads collection.json → finds "component" entry → factory path

     │
     ▼
JSON Schema Validation
──────────────────────
Merges CLI flags + prompts against schema.json
Validates required fields, applies defaults
Prompts user for missing required options

     │
     ▼
Factory Function Invoked
─────────────────────────
schematic(options) → returns root Rule

     │
     ▼
Engine Creates Tree
────────────────────
Base layer  = current workspace on disk
Staging layer = empty (no mutations yet)

     │
     ▼
Rule Chain Executes
────────────────────
Rule 1: Generate files from templates → staged
Rule 2: Update angular.json            → staged
Rule 3: Add import to app.module.ts    → staged

     │
     ▼
Post-Rule Tasks Run
────────────────────
NodePackageInstallTask (if scheduled)
RunSchematicTask (chained schematics)

     │
     ▼
Commit (unless --dry-run)
──────────────────────────
Staging layer flushed to real disk
Console output: CREATE / UPDATE / DELETE logs

Exploring the Built-in Schematics Collection

The best way to learn schematic patterns is to read production-grade schematics. The entire @schematics/angular package is open source and worth studying carefully.

# Install to inspect locally
npm install @schematics/angular --save-dev

# Browse on GitHub:
# github.com/angular/angular-cli/tree/main/packages/schematics/angular

# List all available schematics in the built-in collection
ng generate --help

Inside @schematics/angular you'll find the implementation for every built-in generator: component, service, module, guard, pipe, directive, class, enum, interface, and application. Each one follows the same pattern: a schema.json defining options, an index.ts factory, and a files/ directory of templates.

Schematic	Location	Interesting Technique
`component`	`/component/`	Conditional template rendering based on `--standalone`
`module`	`/module/`	Routing module generation, lazy-load wiring
`guard`	`/guard/`	Multiple implementations based on `--implements` flag
`application`	`/application/`	Complete workspace scaffolding, cross-schematic calls

💡 Practical Tip: When learning schematics, clone the Angular CLI repo and read the component schematic in its entirety. It demonstrates conditional template inclusion, AST-based module updates, path normalization, and option defaults — all the patterns you'll use in production schematics.

When to Create Custom Schematics

Having established the technical foundation, the natural question is: when does writing a custom schematic become the right investment?

Repeated scaffolding patterns. If your team frequently creates a "feature module" that always includes a component, a service, a store, and a routing module — and that setup consistently takes 15 minutes of copy-pasting — you have a schematic waiting to be written. A single ng generate feature dashboard should handle it in under a second.

Enforcing architectural rules. Custom schematics are a powerful mechanism for ensuring generated code follows your team's conventions. Folder structures, naming patterns, required barrel files, mandatory test setups — all of these can be encoded into a schematic rather than documented in a wiki that no one reads.

Library installation complexity. If your internal UI library requires updating angular.json, modifying global styles, adding a provider to app.config.ts, and installing two peer dependencies — an ng add schematic automates all of that into a single, repeatable, idempotent operation.

Framework migrations. When you introduce a breaking change in your shared library — a renamed method, a restructured API, a changed import path — an ng update schematic can apply that migration automatically across every workspace that consumes your library. This is how Angular itself ships breaking changes responsibly.

🚦 The Decision Test: Ask yourself: "Would I describe this task in an onboarding doc?" If yes, the task is probably worth automating with a schematic. Documentation describes what humans should do manually. Schematics eliminate the need for the documentation entirely.

Summary & What's Next

We've covered significant ground. Here's what to take forward:

A schematic is a pure function that describes file system transformations on a virtual, in-memory representation of the workspace. The Angular CLI maps its core commands directly to schematics declared in package manifests. The DevKit runtime is built on four core abstractions:

Tree — virtual file system with a staging layer
Rule — atomic, composable unit of transformation
Source — template file origin that produces a new Tree
SchematicContext — runtime connection for logging and task scheduling

The virtual file system is the design decision that enables everything valuable about schematics: dry-run previews, atomic rollback, and millisecond-fast unit testing. The execution pipeline runs schema validation, factory invocation, rule chain execution, task scheduling, and a final atomic commit.

Understanding this architecture deeply is not just academic. It is the precise foundation upon which every practical schematic is built. In Part 2, we take this knowledge directly into the editor and build our first real custom generator — a feature module scaffolder that produces a complete, production-ready module structure in a single command.

Series Roadmap

Part	Topic	Status
Part 1	Understanding Angular Schematics — Architecture & Core Concepts	✅ You are here
Part 2	Creating Custom Generators with `ng generate`	🔜 Coming Soon
Part 3	Building Installation Schematics with `ng add`	🔜 Coming Soon
Part 4	Writing Migration Schematics with `ng update`	🔜 Coming Soon
Part 5	Testing Schematics with Angular DevKit	🔜 Coming Soon
Part 6	Advanced Patterns, Publishing & Monorepo Integration	🔜 Coming Soon

Previous Blogs:

https://dev.to/sakthicodes22/the-nx-cheatsheet-commands-for-daily-development-3h4k
https://dev.to/sakthicodes22/stop-the-spaghetti-enforcing-module-boundaries-in-an-nx-monorepo-2a24

Found this useful? Drop a ❤️ and share it with a teammate who would be intersted.

The Nx Cheatsheet — Commands for Daily Development

Sakthikumaran Navakumar — Mon, 02 Mar 2026 15:17:27 +0000

If you have just started working with Nx — or joined a team that uses it — the CLI can feel overwhelming at first. There are dozens of commands, flags, and concepts to absorb all at once.

This cheatsheet cuts through the noise. It covers the commands you will actually use every day, organised by workflow, explained plainly. Bookmark it, come back to it, share it with your team. Complete List of CLI commands can be found here.

📋 Table of Contents

What is Nx?
Creating a Workspace
Adding Plugins
Generating Projects and Code
Running and Serving Applications
Running Multiple Tasks
Filtering Projects with Patterns and Tags
Building Projects
The Affected Commands
Skipping and Managing the Cache
Running Tests
Linting and Formatting
Visualising the Dependency Graph
Workspace and Project Info
The Nx Daemon
Quick Reference Cheat Sheet

What is Nx?

Nx is an open-source build system and monorepo toolkit. It lets you manage all your applications and shared libraries in a single repository while giving you intelligent tooling to build, test, and serve them efficiently.

Three things make Nx stand out:

🧠 Smart task runner — understands your project dependency graph and only rebuilds what has actually changed
🏗️ Code generation — scaffolds apps, libraries, and components using best-practice templates
📊 Visualisation — interactive graph to see how all your projects connect

1. Creating a Workspace

Everything starts here. A workspace is the root container for all your applications and libraries.

# Create a new workspace interactively
npx create-nx-workspace@latest

# Create with a specific framework preset
# (react, angular, next, node, ts, empty)
npx create-nx-workspace@latest --preset=react

# Create a blank monorepo with a custom name
npx create-nx-workspace@latest --preset=empty --name=myorg

# Specify your preferred package manager (npm, yarn, pnpm)
npx create-nx-workspace@latest --packageManager=pnpm

# Add Nx to an already-existing project or monorepo
nx init

2. Adding Plugins

Nx is plugin-driven. Plugins provide the framework-specific generators and executors for React, Angular, Node, and more. The nx add command installs a plugin and automatically runs its initialisation generator in one step — no manual wiring required.

# Install the React plugin and auto-initialize it
nx add @nx/react

# Install the Angular plugin and wire it up automatically
nx add @nx/angular

3. Generating Projects and Code

Instead of manually creating folders and configuration files, let Nx do it for you. The nx generate (or nx g) command creates everything following best practices for your chosen framework.

# Generate a new application
nx g app <n>

# Generate a new shared library
nx g lib <n>

# Generate a component (framework-specific)
nx g component <n>

# Preview what will be generated WITHOUT writing any files
nx g app <n> --dry-run

4. Running and Serving Applications

Nx provides a consistent interface for running your projects regardless of which framework or tooling is underneath. nx serve myapp is shorthand for nx run myapp:serve — both do the same thing.

# Start a local development server
nx serve <project>

# Run any defined target on a project
nx run <project>:<target>

# Run a target with a specific configuration (e.g. production, staging)
nx run <project>:<target>:<configuration>

5. Running Multiple Tasks

As your monorepo grows, you need to run operations across multiple projects at once. nx run-many fans out work across your workspace in parallel. The default parallelism is 3 — increase it based on your machine's capacity.

# Run multiple targets across ALL projects in one command
nx run-many -t build test lint

# Run multiple targets on specific named projects only
nx run-many -t build test lint -p app1 app2

# Run tasks with a concurrency limit
nx run-many -t build --parallel=5

# Run with the interactive Terminal UI (new in Nx v22)
nx run-many -t build --outputStyle=tui

6. Filtering Projects with Patterns and Tags

Instead of listing every project name manually, use glob patterns and Nx project tags to target exactly the right set of projects. Tags are labels you assign to projects in their config — for example scope:frontend or type:ui.

# Run only projects tagged with scope:frontend
nx run-many -t build --projects='tag:scope:frontend'

# Run only projects whose names end with -app
nx run-many -t build --projects='*-app'

# Mix explicit names and glob patterns
nx run-many -t test --projects='app1,app2,shared-*'

# Run on all projects, EXCLUDING e2e projects
nx run-many -t lint --exclude='*-e2e'

7. Building Projects

Building compiles your source code and produces deployment-ready artifacts. The command is the same regardless of whether you use Webpack, Vite, or esbuild underneath.

# Build a specific project
nx build <project>

# Build using the production configuration (optimised, minified)
nx build <project> --configuration=production

# Build all projects in the workspace
nx run-many -t build

8. The Affected Commands — Nx's Superpower

This is the feature that makes Nx genuinely transformative. Instead of rebuilding and retesting everything on every commit, Nx analyses your dependency graph and figures out exactly which projects are affected by your changes — and only runs tasks for those.

If you change a utility library, Nx identifies every app and library that depends on it and runs the target for all of them. Everything else is skipped. On a large monorepo, this can reduce CI time significantly.

# Build only projects affected by recent changes
nx affected -t build

# Test only affected projects
nx affected -t test

# Lint only affected projects
nx affected -t lint

# Run multiple targets on affected projects in one command
nx affected -t build test lint

# Determine affected projects relative to a specific branch/commit range
nx affected --base=main --head=HEAD

9. Skipping and Managing the Cache

Nx caches the results of every task. If nothing has changed since the last run, Nx replays the cached result in milliseconds. There are times, however, when you need to bypass the cache — debugging a flaky test, verifying a fix actually works, or clearing stale output.

Refer here for How caching works

# Run a build bypassing the local cache entirely
nx build <project> --skipNxCache

# Skip cache for all projects in run-many
nx run-many -t build --skipNxCache

# Skip cache on all affected test runs
nx affected -t test --skipNxCache

# Clear the entire local cache AND daemon state
nx reset

# Clear ONLY the task cache, leave the daemon running
nx reset --only-cache

# Restart ONLY the daemon, leave the cache intact
nx reset --only-daemon

10. Running Tests

Whether your projects use Jest, Vitest, Playwright, or Cypress, nx test and nx e2e provide a consistent interface. Combine with affected and run-many for full-scale coverage.

# Run unit tests for a specific project
nx test <project>

# Run end-to-end tests for a project
nx e2e <project>

# Run unit tests only for affected projects
nx affected -t test

# Run unit tests across ALL projects
nx run-many -t test

11. Linting and Formatting

Keeping code quality consistent across a monorepo is hard without tooling. Nx gives every project its own lint target and provides workspace-level format commands powered by Prettier.

# Lint a specific project
nx lint <project>

# Lint only the projects affected by recent changes
nx affected -t lint

# Auto-format ALL files in the workspace using Prettier
nx format:write

# Check formatting across the workspace WITHOUT writing (perfect for CI)
nx format:check

12. Visualising the Dependency Graph

At any point you can visualise the entire architecture of your monorepo as an interactive browser-based graph. This is invaluable for onboarding new team members, auditing architecture, and understanding the blast radius of a change.

# Open the interactive dependency graph in the browser
nx graph

# Show only the subgraph of a specific project and its dependencies
nx graph --focus=<project>

# Print the project graph as JSON to the terminal
nx graph --print

# Export the full graph to a JSON file
nx graph --file=output.json

13. Workspace and Project Info

As your workspace grows, you need reliable ways to explore it. The nx show, nx list, and nx report commands answer the everyday questions: what exists, what is affected, what plugins are installed.

# List ALL projects in the workspace
nx show projects

# List only the projects affected by recent changes
# (modern replacement for the deprecated nx affected:apps/libs)
nx show projects --affected

# List all projects that have a specific target defined
nx show projects --with-target serve

# Show full configuration details of a specific project
nx show project <n>

# Open a rich browser view of a project's fully resolved configuration
nx show project <n> --web

# List all installed Nx plugins in the workspace
nx list

# List all generators and executors provided by a specific plugin
nx list <plugin>

# Print all installed Nx and plugin versions (essential for debugging)
nx report

14. The Nx Daemon

The Nx Daemon is a background process that keeps your workspace's project graph in memory. Without it, every command has to re-read and re-parse your entire workspace from scratch — noticeable latency in large monorepos. In most cases it starts and stops automatically. These commands give you manual control when needed.

# Manually start the Nx daemon
nx daemon --start

# Stop the Nx daemon
nx daemon --stop

⚡ Quick Reference Cheat Sheet

🏗️ Workspace Setup

Command	What it does
`npx create-nx-workspace@latest`	Create a new workspace
`nx init`	Add Nx to an existing project
`nx add @nx/react`	Add and initialize a plugin

🔧 Generate Code

Command	What it does
`nx g app <n>`	New application
`nx g lib <n>`	New shared library
`nx g component <n>`	New component
`nx g app <n> --dry-run`	Preview generation without writing files

▶️ Run Tasks

Command	What it does
`nx serve <project>`	Start dev server
`nx build <project>`	Build a project
`nx test <project>`	Run unit tests
`nx e2e <project>`	Run e2e tests
`nx lint <project>`	Lint a project

🚀 Scale Across Projects

Command	What it does
`nx run-many -t build test lint`	Run multiple targets across all projects
`nx run-many -t build --parallel=5`	Run with concurrency control
`nx run-many -t build --projects='*-app'`	Target projects by glob pattern
`nx run-many -t build --projects='tag:scope:frontend'`	Target projects by tag
`nx run-many -t lint --exclude='*-e2e'`	Exclude projects by pattern
`nx affected -t build test lint`	Only run what is affected by your changes
`nx affected --base=main --head=HEAD`	Affected in a PR commit range

🗄️ Cache Management

Command	What it does
`nx build <project> --skipNxCache`	Bypass cache for one task
`nx reset --only-cache`	Clear task cache only
`nx reset --only-daemon`	Restart daemon only
`nx reset`	Full reset — cache + daemon

🔍 Explore & Debug

Command	What it does
`nx graph`	Open interactive dependency graph
`nx graph --focus=<project>`	Focus graph on one project
`nx show projects --affected`	List affected projects
`nx show project <n> --web`	Inspect full project config in browser
`nx report`	Check all installed plugin versions
`nx format:check`	Check formatting (great for CI)
`nx format:write`	Auto-format the entire workspace

Useful Links

📖 Official Nx Documentation
🔧 Nx CLI Reference (v22)

Found this useful? Drop a ❤️ and share it with a teammate who is just getting started with Nx.

Stop the Spaghetti: Enforcing Module Boundaries in an Nx Monorepo

Sakthikumaran Navakumar — Sat, 28 Feb 2026 14:44:59 +0000

Enforcing Module Boundaries in an Nx Monorepo

It starts with good intentions. Your team decides to adopt a monorepo. You scaffold your workspace, create a handful of libraries, and for the first few sprints everything feels clean and purposeful. Then the deadlines hit.

A developer needs a formatting utility from the payments module — so they reach in and import it directly. Another engineer needs a component from the loans feature for a quick prototype in the accounts section. Someone else, pressed for time, imports a service three layers deep from another domain's internals. Nobody reviews it too carefully. The CI pipeline is green. Ship it.

Six months later, your dependency graph looks like a bowl of spaghetti. The payments domain knows about accounts. The accounts feature imports from loans. Shared utilities carry domain-specific logic. Nobody can confidently change anything without triggering a cascade of broken imports across the workspace. Your architecture diagram, proudly mounted on the team's Confluence page, bears no resemblance to what the codebase actually does.
This is not a discipline problem. It is a tooling problem. And Nx solves it elegantly.

Why Module Boundaries Matter: The Architectural Case

Before we look at the tooling, it is worth understanding why boundary enforcement is not just a nice-to-have but an architectural necessity in any sufficiently large codebase.

Implicit Coupling Is the Silent Killer

In a monorepo without enforced boundaries, any library can import from any other library. Technically, there is nothing stopping a UI component from reaching directly into a data-access service, or a feature module from importing internal implementation details from a completely unrelated domain. These imports create implicit coupling — undocumented, invisible dependencies that accumulate quietly until refactoring becomes genuinely dangerous.

Social Enforcement Does Not Scale

With a team of three engineers and ten libraries, you can maintain architectural discipline through code review and shared understanding. With a team of fifteen engineers, forty libraries, and three concurrent feature tracks, you cannot. The cognitive overhead of manually auditing import paths in code review is enormous, the feedback loop is slow, and violations slip through. You need the tooling to carry the architectural intent forward, independent of team size, experience level, or deadline pressure.

The Architecture Diagram Should Match the Import Graph

This is the principle that underpins everything. If your architecture diagram shows that the payments domain is isolated from the loans domain, then your import graph should reflect exactly that. Nx module boundary enforcement is the mechanism that keeps these two things in sync — automatically, continuously, and without relying on human vigilance.

The Nx Mental Model: Tags and Dependency Constraints

Nx enforces boundaries through a tag-based system. Each library in your workspace is assigned one or more tags via its project.json file, and your ESLint configuration defines rules that govern which tags are allowed to depend on which other tags.

Tags typically carry two dimensions of information: scope and type.

Scope answers the question: which domain or vertical does this library belong to? In a banking application, you might have scopes like scope:payments, scope:loans, scope:accounts, scope:kyc (Know Your Customer), and scope:shared.

Type answers the question: what architectural layer or role does this library play? Rather than the generic feature/ui/data-access/util convention, a more expressive and flexible approach uses tags like type:app, type:lib, type:shared, and type:e2e. This maps more naturally to how libraries actually behave in large-scale production workspaces and gives you coarser, more durable rules.

Here is how tags are applied in a library's project.json:

//apps/banking-portal-e2e/project.json
{
  "name": "banking-portal-e2e",
  "projectType": "application",
  "tags": ["scope:banking-portal", "type:e2e"]
}

Once your libraries are tagged, the ESLint rule @nx/enforce-module-boundaries becomes the enforcement engine.

The Sample Project Structure

Before diving into the ESLint configuration, here is the workspace structure we will be working with throughout this article. This represents a simplified but realistic banking platform monorepo.

banking-workspace/
├── apps/
│   ├── banking-portal/       # Customer-facing web app
│   │   └── project.json      # tags: scope:banking-portal, type:app
│   ├── banking-portal-e2e/   # E2E tests for banking-portal
│   │   └── project.json      # tags: scope:banking-portal, type:e2e
│   ├── admin-dashboard/      # Internal ops/admin app
│       └── project.json      # tags: scope:admin, type:app  
├── libs/
│   ├── payments/
│   │   ├── feature-transfer/ # tags: scope:payments, type:lib
│   │   ├── feature-transaction-history/ # tags: scope:payments, type:lib
│   │   └── data-access/      # tags: scope:payments, type:lib
│   ├── loans/
│   │   ├── feature-apply/    # tags: scope:loans, type:lib
│   │   ├── feature-repayment/# tags: scope:loans, type:lib
│   │   └── data-access/      # tags: scope:loans, type:lib
│   ├── accounts/
│   │   ├── feature-dashboard/# tags: scope:accounts, type:lib
│   │   ├── feature-settings/ # tags: scope:accounts, type:lib
│   │   └── data-access/      # tags: scope:accounts, type:lib
│   ├── kyc/
│   │   ├── feature-onboarding/# tags: scope:kyc, type:lib
│   │   └── data-access/       # tags: scope:kyc, type:lib
│   └── shared/
│       ├── ui-design-system/  # tags: scope:shared, type:shared
│       ├── ui-forms/          # tags: scope:shared, type:shared
│       ├── util-formatters/   # tags: scope:shared, type:shared
│       ├── util-validators/   # tags: scope:shared, type:shared
│       └── data-access-http/  # tags: scope:shared, type:shared

Every domain (payments, loans, accounts, kyc) is a self-contained vertical. The shared scope holds anything that is genuinely cross-cutting. Apps consume libs. Libs do not reach into other domain's libs unless explicitly permitted. E2E projects only test — they never become a source of shared logic.

Enforcing Boundaries with the Nx ESLint Plugin

With the project structure established, let us look at the ESLint configuration that encodes these architectural rules. All of this lives in your root .eslintrc.json.

{
  "root": true,
  "plugins": ["@nx"],
  "overrides": [
    {
      "files": ["*.ts", "*.tsx", "*.js", "*.jsx"],
      "rules": {
        "@nx/enforce-module-boundaries": [
          "error",
          {
            "enforceBuildableLibDependency": true,
            "allowCircularSelfDependency": true,
            "banTransitiveDependencies": true,
            "depConstraints": [

              {
                "sourceTag": "type:app",
                "onlyDependOnLibsWithTags": ["type:lib", "type:shared"]
              },

              {
                "sourceTag": "type:lib",
                "onlyDependOnLibsWithTags": ["type:lib", "type:shared"]
              },

              {
                "sourceTag": "type:shared",
                "onlyDependOnLibsWithTags": ["type:shared"]
              },

              {
                "sourceTag": "type:e2e",
                "onlyDependOnLibsWithTags": ["type:shared"]
              },

              {
                "sourceTag": "scope:payments",
                "onlyDependOnLibsWithTags": ["scope:payments", "scope:shared"]
              },
              {
                "sourceTag": "scope:loans",
                "onlyDependOnLibsWithTags": ["scope:loans", "scope:shared"]
              },
              {
                "sourceTag": "scope:accounts",
                "onlyDependOnLibsWithTags": ["scope:accounts", "scope:shared"]
              },
              {
                "sourceTag": "scope:kyc",
                "onlyDependOnLibsWithTags": ["scope:kyc", "scope:shared"]
              },
              {
                "sourceTag": "scope:shared",
                "onlyDependOnLibsWithTags": ["scope:shared"]
              }

            ]
          }
        ]
      }
    }
  ]
}

This configuration encodes six architectural decisions simultaneously:

Apps can consume domain libs and shared libs — but never other apps
Domain libs can consume other libs within their own scope and anything in shared — but never reach across domain boundaries
Shared libs are the foundation layer — they are self-contained and import nothing outside their own scope
E2E projects can reference shared utilities if needed, but are otherwise isolated from application and domain logic
banTransitiveDependencies ensures that if lib A depends on lib B which depends on lib C, lib A cannot import from lib C directly — it must go through lib B's public API
enforceBuildableLibDependencyCheck ensures that if you enable buildable libs, your dependency declarations stay honest

Advanced Tag Expressions: !, *, and Combining Constraints

One of the most underused and underappreciated features of the @nx/enforce-module-boundaries rule is its support for tag expression operators. Beyond simple string matching, the rule supports negation, wildcards, and compound logic that lets you write precise, expressive constraints.

The Wildcard Operator: *

The wildcard * matches any tag. This is useful when you want to say "this library can import from literally anything" — which you should use sparingly, but it has legitimate use cases for certain shell or orchestration libraries.

{
  "sourceTag": "type:app",
  "onlyDependOnLibsWithTags": ["*"]
}

More practically, wildcards shine when used within a tag expression for partial matching. For example, if you want to allow a shared utility to depend on any shared library regardless of a sub-classification:

json
{
  "sourceTag": "scope:shared",
  "onlyDependOnLibsWithTags": ["scope:shared", "*:shared"]
}

You can also use ! directly within the onlyDependOnLibsWithTags array to say "must have this tag and must not have that tag simultaneously":

json{
  "sourceTag": "scope:accounts",
  "onlyDependOnLibsWithTags": ["scope:accounts", "scope:shared", "!type:e2e"]
}

This reads as: "accounts-scoped libraries may only depend on libraries that are tagged scope:accounts or scope:shared, and in all cases, those libraries must not be tagged type:e2e." This is particularly useful when your shared scope contains a mix of test utilities and production utilities that you want to distinguish at the dependency constraint level.

Violations in Action: What This Looks Like in Your IDE
Let us see what happens when a developer violates one of these rules. This is arguably the most important section of the article because it shows the tangible developer experience of boundary enforcement.
typescript// libs/payments/feature-transfer/src/lib/transfer.component.ts


// ✅ ALLOWED — payments lib importing from its own domain
import { PaymentsApiService } from '@banking/payments/data-access';

// ✅ ALLOWED — payments lib importing from shared scope
import { CurrencyFormatterPipe } from '@banking/shared/util-formatters';
import { ButtonComponent } from '@banking/shared/ui-design-system';

// ❌ VIOLATION — crossing domain boundaries
import { LoanEligibilityService } from '@banking/loans/data-access';
// ESLint Error: "A project tagged with 'scope:payments' can only depend on 
// libs tagged with 'scope:payments' or 'scope:shared'"

// ❌ VIOLATION — lib importing from an app
import { AppConfig } from '@banking/banking-portal';
// ESLint Error: "A project tagged with 'type:lib' cannot depend on 
// libs tagged with 'type:app'"

// ❌ VIOLATION — reaching into e2e project
import { MockApiInterceptor } from '@banking/banking-portal-e2e';
// ESLint Error: "Imports of e2e projects are not permitted"

These errors surface in real time in VS Code (with the ESLint extension installed).

The Architectural Payoff

Once module boundaries are in place and running in CI, the benefits compound over time in ways that go well beyond code organization.

Your architecture becomes self-documenting. A new engineer joining the banking platform team can read the ESLint configuration and understand the entire domain structure and dependency rules in under five minutes. The rules tell the same story as the architecture diagram — because they are the architecture diagram, expressed as code.
Code reviews become faster and more focused. Reviewers no longer need to manually audit import paths or ask questions like "should payments really know about loans?" The linter has already answered that question before the pull request was opened. Reviews can focus entirely on logic, correctness, and intent.
Refactoring becomes safe. Because every library exposes only what its index.ts exports, and because boundaries prevent cross-domain imports, you can refactor a library's internals with surgical confidence. The blast radius of any change is bounded by the public API surface.
Teams can work in parallel without stepping on each other. When domain boundaries are enforced, the payments team and the loans team genuinely cannot create accidental dependencies between their work. Conway's Law works in your favour: the organizational structure is mirrored by — and protected by — the module boundary rules.
The architecture survives team turnover. Senior engineers who understand the original design decisions eventually leave. Without tooling, their architectural intent leaves with them. With boundary enforcement, the decisions are encoded in the linting configuration and outlive any individual contributor.

The companion repository for this article, including the full workspace structure, ESLint configuration, sample library implementations, and intentional violations with their error output, is available at github. Clone it, break the rules, and watch the linter push back.

github: https://github.com/sakthikumaran22/nx-module-boundaries-demo

Reference: