nx-monorepo

Original：🇺🇸 English

Translated

4 scripts

Nx monorepo management skill for AI-native development. This skill should be used when working with Nx workspaces, project graphs, affected detection, code generation, and caching. Use when analyzing dependencies, running affected commands, generating code, configuring Nx Cloud, or optimizing build performance. Invoke nx-mcp tools for documentation queries.

2installs

Sourcepanaversity/agentfactory

Added on2026-02-24

NPX Install

npx skill4agent add panaversity/agentfactory nx-monorepo

SKILL.md Content

View Translation Comparison →

Nx Monorepo

Overview

This skill provides expert-level capabilities for Nx monorepo management. Nx is the standard build orchestrator for this AI-native platform.

Why Nx: TypeScript-native, 5-minute setup, auto-generates CLAUDE.md/AGENTS.md for AI assistants, excellent CLI tooling.

Documentation Lookup (On-Demand MCP)

Query Nx documentation via on-demand MCP (no persistent server, 0 startup tokens):

bash

# Query Nx docs
bash scripts/nx-docs.sh "how to configure caching"
bash scripts/nx-docs.sh "affected command options"

# List available plugins
bash scripts/nx-plugins.sh

How it works: Scripts spawn

nx-mcp

on-demand via stdio, avoiding persistent MCP connections that consume startup tokens.

Key Insight: Use Nx CLI for operations, scripts for documentation lookup.

Core CLI Commands

Project Graph Analysis

bash

# View interactive project graph
nx graph

# JSON output for programmatic use
nx graph --file=output.json

# Show dependencies of specific project
nx graph --focus=my-app

# Show what depends on a project
nx graph --affected

Affected Detection

bash

# What's affected since main?
nx affected -t build
nx affected -t test
nx affected -t lint

# Compare against specific base
nx affected -t build --base=origin/main --head=HEAD

# Show affected projects only
nx show projects --affected

Running Tasks

bash

# Run task for all projects
nx run-many -t build
nx run-many -t test

# Run for specific projects
nx run-many -t build --projects=app-a,lib-b

# Run with parallelism control
nx run-many -t build --parallel=4

# Single project
nx build my-app
nx test my-lib

Code Generation

bash

# List available generators
nx list @nx/next
nx list @nx/react

# Generate new application
nx g @nx/next:app my-app
nx g @nx/react:app my-frontend

# Generate library
nx g @nx/js:lib shared-utils
nx g @nx/react:lib ui-components

# Dry run (preview)
nx g @nx/next:app my-app --dry-run

Configuration Files

nx.json (Workspace Config)

json

{
  "targetDefaults": {
    "build": {
      "dependsOn": ["^build"],
      "cache": true
    },
    "test": {
      "cache": true
    },
    "lint": {
      "cache": true
    }
  },
  "namedInputs": {
    "default": ["{projectRoot}/**/*"],
    "production": ["default", "!{projectRoot}/**/*.spec.ts"]
  },
  "defaultBase": "main"
}

project.json (Project Config)

json

{
  "name": "my-app",
  "projectType": "application",
  "targets": {
    "build": {
      "executor": "@nx/next:build",
      "outputs": ["{options.outputPath}"],
      "options": {
        "outputPath": "dist/apps/my-app"
      }
    },
    "serve": {
      "executor": "@nx/next:server",
      "options": {
        "buildTarget": "my-app:build"
      }
    }
  }
}

Caching

Local Cache

bash

# Cache is automatic for cacheable targets
nx build my-app  # First run: executes
nx build my-app  # Second run: cached (instant)

# Clear cache
nx reset

Nx Cloud (Remote Cache)

bash

# Connect to Nx Cloud
npx nx connect

# Or add manually
nx g @nx/workspace:ci-workflow

# Verify connection
nx run-many -t build
# Look for: "Remote cache hit"

Cache Inputs

json

// In project.json or nx.json
{
  "targets": {
    "build": {
      "inputs": [
        "default",
        "^production",
        { "externalDependencies": ["next"] }
      ]
    }
  }
}

Common Patterns

Adding a New JS/TS App

bash

# 1. Add plugin (if not already installed)
pnpm nx add @nx/next    # For Next.js
pnpm nx add @nx/react   # For React
pnpm nx add @nx/node    # For Node/Express

# 2. Generate app
pnpm nx g @nx/next:app dashboard --directory=apps/dashboard

# 3. Verify in graph
pnpm nx graph --focus=dashboard

# 4. Build & Serve
pnpm nx build dashboard
pnpm nx serve dashboard

Adding a Python App (uv Workspace)

Python projects use uv workspaces (similar to pnpm workspaces for JS) with manual

project.json

for Nx:

bash

# 1. Create directory and initialize
mkdir -p apps/my-python-app
cd apps/my-python-app
uv init
uv add --group dev pytest ruff mypy
cd ../..

# 2. Add to uv workspace (root pyproject.toml)

Edit root

pyproject.toml

toml

[tool.uv.workspace]
members = [
    "apps/panaversity-fs-py",
    "apps/my-python-app",  # Add new project here
]

bash

# 3. Sync all Python deps from root
uv sync --extra dev

apps/my-python-app/project.json (for Nx):

json

{
  "name": "my-python-app",
  "projectType": "application",
  "targets": {
    "build": {
      "command": "uv build",
      "options": { "cwd": "apps/my-python-app" }
    },
    "test": {
      "command": "uv run --extra dev pytest",
      "options": { "cwd": "apps/my-python-app" }
    },
    "lint": {
      "command": "uv run --extra dev ruff check .",
      "options": { "cwd": "apps/my-python-app" }
    }
  }
}

bash

# 4. Verify Nx recognizes it
pnpm nx show projects
pnpm nx graph --focus=my-python-app

# 5. Run tasks via Nx
pnpm nx test my-python-app

Shared Python Libraries

Create libraries that multiple Python apps can import:

bash

mkdir -p libs/auth-common-py
cd libs/auth-common-py
uv init --lib
cd ../..
# Add to workspace members, then uv sync

Reference in dependent projects:

toml

# apps/my-python-app/pyproject.toml
[project]
dependencies = ["auth-common-py"]

[tool.uv.sources]
auth-common-py = { workspace = true }

Key Insight: uv manages Python deps via workspace, Nx orchestrates tasks. Single

uv.lock

at root.

Creating Shared Libraries

bash

# JS/TS UI library
pnpm nx g @nx/react:lib ui --directory=libs/shared/ui

# JS/TS Utility library
pnpm nx g @nx/js:lib utils --directory=libs/shared/utils

# Domain library
pnpm nx g @nx/js:lib auth --directory=libs/domain/auth

CI Pipeline (GitHub Actions)

yaml

name: CI
on: [push, pull_request]

jobs:
  main:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - uses: pnpm/action-setup@v2
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: 'pnpm'

      - run: pnpm install --frozen-lockfile

      # Affected-only builds
      - run: npx nx affected -t lint build test --base=origin/main

Troubleshooting

"Cannot find project"

bash

# Regenerate project graph
nx reset
nx graph

Cache Not Working

bash

# Verify target is cacheable
cat nx.json | grep -A5 "targetDefaults"

# Check inputs are stable
nx build my-app --verbose

Dependency Issues

bash

# Show project dependencies
nx graph --focus=my-app

# Check for circular deps
nx graph --file=graph.json
# Review edges in JSON

Quick Reference

Task	Command
Interactive graph	`pnpm nx graph`
Affected build	`pnpm nx affected -t build`
Run all tests	`pnpm nx run-many -t test`
Generate JS/TS app	`pnpm nx g @nx/next:app name`
Generate JS/TS lib	`pnpm nx g @nx/js:lib name`
Add plugin	`pnpm nx add @nx/next`
Clear cache	`pnpm nx reset`
Show projects	`pnpm nx show projects`
List generators	`pnpm nx list @nx/next`

Python-Specific (uv)

Task	Command
Init Python project	`cd apps/name && uv init`
Add runtime dep	`uv add <package>`
Add dev dep	`uv add --group dev <package>`
Sync deps	`uv sync --extra dev`
Run via Nx	`pnpm nx test my-python-app`

Related Skills

monorepo-workflow: PR stacking, trunk-based development, code review
monorepo-team-lead: CODEOWNERS, human-AI task routing, RFC process

nx-monorepo

NPX Install

Tags

SKILL.md Content

Nx Monorepo

Overview

Documentation Lookup (On-Demand MCP)

Core CLI Commands

Project Graph Analysis

Affected Detection

Running Tasks

Code Generation

Configuration Files

nx.json (Workspace Config)

project.json (Project Config)

Caching

Local Cache

Nx Cloud (Remote Cache)

Cache Inputs

Common Patterns

Adding a New JS/TS App

Adding a Python App (uv Workspace)

Shared Python Libraries

Creating Shared Libraries

CI Pipeline (GitHub Actions)

Troubleshooting

"Cannot find project"

Cache Not Working

Dependency Issues

Quick Reference

Python-Specific (uv)

Related Skills