Workspace patterns

Nx Workspace Patterns

Navigation hub for Nx workspace architecture and operations.

When to Use

• You are structuring or refactoring an Nx monorepo.
• You need dependency boundaries enforced by tags and lint rules.
• You need reliable affected-command CI and caching performance.

When Not to Use

• The repository is single-project with no monorepo coordination needs.
• The task is framework-specific build setup unrelated to Nx graph and task orchestration.

Workflow

1. Structure workspace domains (apps/, libs/, tools/).
2. Define tags and project graph conventions.
3. Configure target pipelines and caching defaults.
4. Enforce module boundaries and verify violations fail with nx lint --skip-nx-cache.
5. Integrate affected commands in CI with explicit base/head strategy.

Constraint Guidelines

Hard Constraints

• MUST tag projects consistently for scope/type-based constraints.
• MUST configure targetDefaults for build/test/lint dependency flow.
• MUST use affected commands in CI for scalable execution.

Flexible Choices

• CAN choose tag vocabulary (scope:*, type:*, platform:*) if consistent.
• CAN choose cache backend (Nx Cloud or self-hosted) by org constraints.
• CAN choose library granularity based on team ownership and release cadence.

Fallback Behaviors

Missing Config	Fallback
no explicit tags	allow broad deps temporarily with warning and migration plan
no target defaults	tasks run independently with reduced optimization
no CI base/head	default to main branch and document tradeoff

Quick Commands

nx graph

nx affected -t lint,test,build --base=origin/main --parallel=3

nx show project my-app --web

nx reset

rg -n "@nx/enforce-module-boundaries|depConstraints" .

Configuration Examples

nx.json targetDefaults

{
  "targetDefaults": {
    "build": {
      "dependsOn": ["^build"],
      "inputs": ["production", "^production"],
      "cache": true
    },
    "test": {
      "dependsOn": ["build"],
      "inputs": ["default", "^production", "{workspaceRoot}/jest.preset.js"],
      "cache": true
    },
    "lint": {
      "inputs": ["default", "{workspaceRoot}/.eslintrc.json"],
      "cache": true
    }
  }
}

ESLint depConstraints (tag-based boundaries)

{
  "overrides": [
    {
      "files": ["*.ts", "*.tsx", "*.js", "*.jsx"],
      "rules": {
        "@nx/enforce-module-boundaries": [
          "error",
          {
            "enforceBuildableLibDependency": true,
            "allow": [],
            "depConstraints": [
              {
                "sourceTag": "scope:web",
                "onlyDependOnLibsWithTags": ["scope:web", "scope:shared"]
              },
              {
                "sourceTag": "type:feature",
                "onlyDependOnLibsWithTags": ["type:feature", "type:ui", "type:data-access", "type:util"]
              },
              {
                "sourceTag": "type:ui",
                "onlyDependOnLibsWithTags": ["type:ui", "type:util"]
              }
            ]
          }
        ]
      }
    }
  ]
}

Anti-Patterns

NEVER create circular dependencies between projects

• WHY: cycles degrade graph clarity and destabilize build ordering.
• BAD: libs/ui depends on libs/data while libs/data depends on libs/ui.
• GOOD: extract shared contracts to a lower-level library.

NEVER run run-many --all in CI as the default verification path

• WHY: full-workspace execution wastes CI budget and slows feedback loops.
• BAD: always build/test every project on each PR.
• GOOD: use nx affected with explicit base/head.

NEVER tag projects inconsistently

• WHY: boundary rules are only as strong as tag consistency.
• BAD: mixed ad hoc tags with no vocabulary.
• GOOD: defined tag taxonomy with lint enforcement.

NEVER skip target pipeline dependencies in targetDefaults

• WHY: missing dependsOn prevents optimal scheduling and can hide ordering bugs.
• BAD: implicit task order assumptions.
• GOOD: explicit dependsOn for build/test/lint behavior.

NEVER ignore cache inputs and outputs for critical targets

• WHY: incomplete cache metadata causes stale hits or unnecessary misses.
• BAD: cache enabled but no stable inputs/outputs.
• GOOD: declare outputs and relevant named inputs per target.

References

Topic	Reference
Project graph and nx.json patterns	references/project-graph-configuration.md
Caching and optimization	references/caching-strategies.md
Boundaries and tags	references/project-boundaries.md
Affected commands and CI	references/affected-commands.md

• Nx Documentation
• Module Boundaries
• Nx Cloud