shared-monorepo-nx

Monorepo Orchestration with Nx

Quick Guide: Nx 22 for monorepo orchestration and build intelligence. Project graph for dependency analysis. Task pipelines with topological ordering and dependsOn. Local computation caching + Nx Cloud remote caching for massive speed gains. Inferred tasks (Project Crystal) auto-detect targets from tool config files. nx affected runs only what changed. nx release for versioning, changelogs, and publishing. Generators scaffold code, executors run tasks.

<critical_requirements>

CRITICAL: Before Using This Skill

All code must follow project conventions in CLAUDE.md (kebab-case, named exports, import ordering, import type, named constants)

(You MUST enable caching with "cache": true on cacheable targets — builds, tests, linting — and set "cache": false or omit for side-effect tasks like serve)

(You MUST define dependsOn: ["^build"] in targetDefaults for build tasks to ensure topological ordering across the project graph)

(You MUST declare inputs and outputs for cached targets so Nx knows what to hash and what to restore)

(You MUST use inferred tasks (Project Crystal) as the default — only add project.json targets when overriding inferred configuration)

(You MUST use nx affected -t <target> in CI to only run tasks for changed projects and their dependents)

</critical_requirements>

Auto-detection: Nx workspace, nx.json, project.json, nx generate, nx affected, nx graph, nx release, @nx/ plugins, Nx Cloud, inferred tasks, Project Crystal, nx migrate, targetDefaults, namedInputs, nx run-many, nx serve

When to use:

• Setting up a new Nx monorepo or adding Nx to an existing repo
• Configuring task pipelines, caching, and dependency ordering in nx.json
• Generating projects, libraries, and components with Nx generators
• Running affected commands to optimize CI builds
• Configuring Nx Cloud for remote caching and distributed task execution
• Managing releases with nx release (versioning, changelogs, publishing)
• Setting up module federation for micro-frontend architectures
• Migrating between Nx versions with nx migrate

When NOT to use:

• Single application with no shared libraries (standard build tools suffice)
• Projects already using Turborepo (do not mix monorepo orchestrators)
• Very small projects where Nx setup overhead exceeds benefits
• When all you need is npm workspaces without task orchestration

Key patterns covered:

• Workspace setup and nx.json configuration
• Task pipelines with targetDefaults and dependsOn
• Local + remote caching strategies
• Inferred tasks (Project Crystal) and plugin system
• Affected commands and project graph
• Generators and executors
• Release management (nx release)
• Module federation for micro-frontends

Examples

• [Workspace Setup](examples/core.md) — Directory structure, nx.json config
• [Task Pipeline & Caching](examples/tasks.md) — dependsOn ordering, namedInputs, cache configuration, affected commands
• [Generators](examples/generators.md) — Built-in generators, custom generators, schemas, migrations
• [CI & Release Management](examples/ci.md) — GitHub Actions, Nx Cloud, release configuration, module federation

Additional resources:

• For CLI reference and decision frameworks, see [reference.md](reference.md)

<philosophy>

Philosophy

Nx is a build intelligence platform for monorepos. Unlike simple task runners, Nx understands the structure of your codebase through the project graph — a directed acyclic graph of projects and their dependencies. This graph enables intelligent task scheduling, fine-grained caching, and affected analysis.

Nx's core value proposition: never run a task that has already been computed, and never run more tasks than necessary.

Key principles:

• Project graph first — Nx analyzes imports, configuration, and dependency relationships to build a graph of your workspace. Every feature (caching, affected, task pipelines) builds on this graph.
• Inferred configuration — Since Project Crystal (Nx 18+), plugins auto-detect tasks from tool configs (vite.config.ts, jest.config.ts, etc.), dramatically reducing boilerplate.
• Computation caching — Every task result is cached by default. Cache keys are computed from file inputs, environment, and dependency graph position.
• Affected analysis — nx affected uses git diff + project graph to determine the minimum set of projects impacted by a change.

When to use Nx:

• Monorepos with multiple apps sharing libraries
• Teams needing remote cache sharing across developers and CI
• Large codebases where build/test times are a bottleneck
• Projects with complex task dependency chains requiring topological ordering
• Organizations wanting enforced module boundaries between teams

When NOT to use Nx:

• Single-app projects with no shared code (Vite/esbuild directly)
• Polyrepo setups where repos are intentionally independent
• Projects already using Turborepo (pick one orchestrator)
• Prototypes or very small projects where setup cost exceeds benefit

</philosophy>

<patterns>

Core Patterns

Pattern 1: Workspace Setup and nx.json Configuration

The nx.json file is the central configuration for task behavior, caching, plugins, and workspace-wide defaults.

{
  "$schema": "./node_modules/nx/schemas/nx-schema.json",
  "namedInputs": {
    "production": [
      "default",
      "!{projectRoot}/**/*.spec.ts",
      "!{projectRoot}/**/*.test.ts"
    ]
  },
  "targetDefaults": {
    "build": {
      "dependsOn": ["^build"],
      "inputs": ["production", "^production"],
      "outputs": ["{projectRoot}/dist"],
      "cache": true
    }
  },
  "plugins": [
    { "plugin": "@nx/vite/plugin", "options": { "buildTargetName": "build" } }
  ]
}

Why good: namedInputs exclude test files from build cache keys, dependsOn: ["^build"] enforces topological ordering, plugins auto-detect targets

For complete nx.json examples, see [examples/core.md](examples/core.md).

Pattern 2: Task Pipelines and Dependency Ordering

Task pipelines define execution order using the dependsOn property. The ^ prefix means "run this target on dependencies first" (topological ordering).

{
  "targetDefaults": {
    "build": { "dependsOn": ["^build"] },
    "test": { "dependsOn": ["build"] },
    "e2e": { "dependsOn": [{ "target": "serve", "params": "ignore" }] },
    "serve": { "continuous": true, "cache": false }
  }
}

• "^build" — Run build on dependency projects first (topological)
• "build" — Run build on the same project first
• { "target": "serve", "params": "ignore" } — Object form, prevents parameter forwarding
• "continuous": true — Long-running task (Nx 21+), dependents start immediately

For pipeline examples and ordering walkthrough, see [examples/tasks.md](examples/tasks.md).

Pattern 3: Computation Caching (Local + Remote)

Nx caches task results locally by default. When inputs have not changed, cached outputs are restored instantly. Nx Cloud extends this with remote caching shared across the team.

{
  "namedInputs": {
    "production": ["default", "!{projectRoot}/**/*.test.ts"]
  },
  "targetDefaults": {
    "build": {
      "inputs": ["production", "^production"],
      "outputs": ["{projectRoot}/dist"],
      "cache": true
    },
    "test": {
      "inputs": [
        "default",
        "^production",
        { "externalDependencies": ["vitest"] }
      ],
      "cache": true
    },
    "serve": { "cache": false, "continuous": true }
  }
}

Key concepts: production excludes test files from build cache keys, externalDependencies invalidates cache on test runner upgrades, cache: false on serve prevents caching dev servers

For cache strategies and namedInputs scenarios, see [examples/tasks.md](examples/tasks.md).

Pattern 4: Inferred Tasks (Project Crystal)

Sinc