git:20260316.063411a to git:20260316.02848e0

---

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

- 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.

```json

{

"$schema": "./node_modules/nx/schemas/nx-schema.json",

"namedInputs": {

"production": [

"default",

"!{projectRoot}/**/*.spec.ts",

},

"targetDefaults": {

"build": {

"dependsOn": ["^build"],

"inputs": ["production", "^production"],

"outputs": ["{projectRoot}/dist"],

"cache": true

}

},

"plugins": [

]

}

```

---

### 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).

```json

{

"targetDefaults": {

}

}

```

---

### 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.

```json

{

"namedInputs": {

},

"targetDefaults": {

"build": {

"inputs": ["production", "^production"],

"cache": true

},

"test": {

"inputs": [

"default",

"^production",

],

"cache": true

},

}

```

---

### Pattern 4: Inferred Tasks (Project Crystal)

```json

{

"plugins": [

{

"plugin": "@nx/vite/plugin",

},

{

"plugin": "@nx/jest/plugin",

"include": ["packages/**/*"],

}

]

}

```

```json

{

"name": "my-app",

"targets": {

}

}

```

---

### Pattern 5: Affected Commands and Project Graph

`nx affected` uses git diff combined with the project graph to determine which projects need to be rebuilt/tested. This is the primary CI optimization.

```bash

```

---

### Pattern 6: Generators (Code Scaffolding)

```json

{

"generators": {

"@nx/react:library": {

"bundler": "vite",

"unitTestRunner": "vitest",

"style": "scss"

}

}

}

```

---

### Pattern 7: Release Management (nx release)

```json

{

"release": {

"projects": ["packages/*"],

"projectsRelationship": "independent",

"changelog": {

"projectChangelogs": {

}

},

}

}

```

```bash

```

---

### Pattern 8: Module Federation (Micro-Frontends)

```bash

```

</patterns>

---

<performance>

## Performance Optimization

**Cache Hit Metrics (typical monorepo with 20+ projects):**

- First build: ~60s (no cache, full workspace)

- Cached build: ~1s (local cache hit, 98% faster)

- Affected build: ~15s (only changed projects, 75% faster)

- Remote cache hit: ~5s (download + restore from Nx Cloud)

- Team savings: 10-40 hours/week with Nx Cloud enabled

**Optimization Strategies:**

```bash

```

</performance>

---

<decision_framework>

## Decision Framework

### When to Use Nx

```

Is this a monorepo with shared code?

├─ NO → Standard build tools (Vite, esbuild, tsc)

└─ YES → Do you need task orchestration and caching?

├─ NO → npm/pnpm/bun workspaces alone may suffice

└─ YES → Do you need a project graph and affected analysis?

├─ YES → Nx

└─ NO → Turborepo may be simpler

```

### Nx vs Turborepo

```

Which monorepo tool?

├─ Need project graph analysis → Nx

├─ Need generators and code scaffolding → Nx

├─ Need module federation support → Nx

├─ Need distributed task execution (Nx Agents) → Nx

├─ Need simplest possible config → Turborepo

├─ Already using Vercel ecosystem → Turborepo

└─ Need polyglot support (.NET, Java, Gradle) → Nx

```

### Where to Put New Code

```

New code to write?

├─ Deployable application → apps/

├─ Shared across 2+ apps → libs/ or packages/

├─ App-specific code → Feature folder within the app

├─ Build tooling or generators → tools/

└─ Shared configuration → packages/ (e.g., eslint-config, tsconfig)

```

### Fixed vs Independent Releases

```

How to version packages?

├─ All packages always release together → "fixed" (default)

├─ Packages have different consumers → "independent"

├─ Internal-only packages → Fixed (simpler)

└─ Published to npm with different audiences → Independent

```

For comprehensive decision trees and anti-patterns, see [reference.md](reference.md).

</decision_framework>

---

<integration>

## Integration Guide

**Works with:**

- **Vite**: `@nx/vite/plugin` infers build/serve/test targets from vite.config.ts

- **Jest / Vitest**: `@nx/jest/plugin` and `@nx/vite/plugin` infer test targets

- **ESLint**: `@nx/eslint/plugin` infers lint targets from eslint.config.js

- **Storybook**: `@nx/storybook` infers build-storybook and storybook targets

- **Nx Cloud**: Remote caching (Nx Replay) and distributed task execution (Nx Agents)

**Replaces / Conflicts with:**

- **Turborepo**: Similar monorepo tool — choose one, not both

- **Lerna**: Nx subsumes Lerna's functionality (Nx team maintains Lerna since v6)

- **Rush**: Microsoft's monorepo tool — Nx provides broader plugin ecosystem

</integration>

---

<red_flags>

## RED FLAGS

**High Priority Issues:**

- Missing `dependsOn: ["^build"]` for build targets — dependencies may not build first, causing import errors

- Missing `cache: true` on cacheable targets — every run recomputes from scratch, negating Nx's primary value

- Caching long-running tasks (dev servers, watch mode) — `serve` and `dev` must have `cache: false`

- Running `nx run-many -t test` in CI instead of `nx affected -t test` — wastes compute on unchanged projects

- Missing `inputs` on cached targets — Nx cannot determine when cache is stale, leading to incorrect cache hits

**Medium Priority Issues:**

- Not using inferred tasks — manually defining every target in `project.json` when plugins can auto-detect

- Missing `namedInputs` for production — test file changes invalidate build caches unnecessarily

- Not connecting to Nx Cloud — every developer rebuilds everything locally instead of sharing cache

- Overly broad `outputs` — caching framework cache directories (`.next/cache/`) bloats cache storage

**Common Mistakes:**

- Using `dependsOn: ["build"]` (same project) when `dependsOn: ["^build"]` (dependency projects) was intended

- Forgetting to set `continuous: true` on serve tasks — dependent e2e tasks wait forever for serve to "complete"

- Running `nx migrate` without `--run-migrations` — migrations are generated but not applied

- Not setting `defaultBase` in nx.json — affected analysis defaults to `main` which may not be your branch

**Gotchas & Edge Cases:**

- `dependsOn: ["^task"]` runs the target on **dependency** projects; `dependsOn: ["task"]` runs it on the **same** project. Mixing these up causes subtle ordering bugs.

- `nx affected` requires git history — in CI, ensure `fetch-depth: 0` (full history) or at least `fetch-depth: 2` for shallow comparison.

- Plugin order in `nx.json` matters — when multiple plugins create the same target name, the last plugin wins.

- `maxCacheSize: "0"` means unlimited, not zero. To disable caching, use `cache: false` on targets.

- Nx merges `project.json` and `package.json` scripts. If both define the same target, `project.json` takes precedence for configuration but `package.json` scripts are still registered as targets.

- `nx reset` clears the local cache AND shuts down the Nx Daemon. Use `nx reset --only-cache` to preserve the daemon.

</red_flags>

---

<critical_reminders>

## CRITICAL REMINDERS

> **All code must follow project conventions in CLAUDE.md**

**(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)**

**Failure to follow these rules will cause incorrect builds, stale caches, wasted CI compute, and broken task ordering.**

</critical_reminders>