/shared-monorepo-nx

name: shared-monorepo-nx
description: Nx monorepo build system — workspace configuration, project graph, task pipelines, caching, generators, plugins, and release management

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": {