pantheon-org/nx-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