Agent skill
nx-monorepo
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.
Install this agent skill to your Project
npx add-skill https://github.com/aiskillstore/marketplace/tree/main/skills/92bilal26/nx-monorepo
SKILL.md
Nx Monorepo
Overview
This skill provides expert-level capabilities for Nx monorepo management. Nx is the standard build orchestrator for this AI-native platform due to its official MCP server integration.
Why Nx: Official MCP server, TypeScript-native, 5-minute setup, auto-generates CLAUDE.md/AGENTS.md for AI assistants.
MCP Tools Available
nx_docs - Query Nx documentation
nx_available_plugins - List official Nx plugins (NOT installed by default)
Key Insight: MCP provides documentation lookup. Use Nx CLI for all operations.
Core CLI Commands
Project Graph Analysis
# 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
# 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
# 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
# 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)
{
"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)
{
"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
# 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)
# 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
// In project.json or nx.json
{
"targets": {
"build": {
"inputs": [
"default",
"^production",
{ "externalDependencies": ["next"] }
]
}
}
}
Common Patterns
Adding a New JS/TS App
# 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:
# 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:
[tool.uv.workspace]
members = [
"apps/panaversity-fs-py",
"apps/my-python-app", # Add new project here
]
# 3. Sync all Python deps from root
uv sync --extra dev
apps/my-python-app/project.json (for Nx):
{
"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" }
}
}
}
# 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:
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:
# 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
# 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)
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"
# Regenerate project graph
nx reset
nx graph
Cache Not Working
# Verify target is cacheable
cat nx.json | grep -A5 "targetDefaults"
# Check inputs are stable
nx build my-app --verbose
Dependency Issues
# 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
Recommended Agent Skills
Expand your agent's capabilities with these related and highly-rated skills.
perigon-backend
Perigon ASP.NET Core + EF Core + Aspire conventions
perigon-agent
Pointers for Copilot/agents to apply Perigon conventions
perigon-angular
Angular 21+ standalone/Material/signal conventions for Perigon WebApp
fastapi-mastery
Comprehensive FastAPI development skill covering REST API creation, routing, request/response handling, validation, authentication, database integration, middleware, and deployment. Use when working with FastAPI projects, building APIs, implementing CRUD operations, setting up authentication/authorization, integrating databases (SQL/NoSQL), adding middleware, handling WebSockets, or deploying FastAPI applications. Triggered by requests involving .py files with FastAPI code, API endpoint creation, Pydantic models, or FastAPI-specific features.
context7-efficient
Token-efficient library documentation fetcher using Context7 MCP with 86.8% token savings through intelligent shell pipeline filtering. Fetches code examples, API references, and best practices for JavaScript, Python, Go, Rust, and other libraries. Use when users ask about library documentation, need code examples, want API usage patterns, are learning a new framework, need syntax reference, or troubleshooting with library-specific information. Triggers include questions like "Show me React hooks", "How do I use Prisma", "What's the Next.js routing syntax", or any request for library/framework documentation.
browser-use
Browser automation using Playwright MCP. Navigate websites, fill forms, click elements, take screenshots, and extract data. Use when tasks require web browsing, form submission, web scraping, UI testing, or any browser interaction.
Didn't find tool you were looking for?