What is nx-workspace used for?

It is for configuring, exploring, and optimizing Nx monorepo workspaces, including analyzing affected projects, caching, and CI/CD workflows. It is not the tool for running tasks or code generation.

How do I view a project's full configuration?

Run nx show project --json to get the complete resolved configuration. Do not rely on project.json directly.

How can I see what will change in a PR?

Use nx show projects --affected --base=main or nx affected -t to identify impacted projects and plan changes accordingly.

nx-workspace

Scanned

npx machina-cli add skill tech-leads-club/agent-skills/nx-workspace --openclaw

Files (1)

SKILL.md

3.9 KB

Nx Workspace Management

Quick Start

Exploring workspace: nx show projects and nx show project <name> --json
Running tasks: nx <target> <project> (e.g., nx build my-app)
Affected analysis: nx show projects --affected or nx affected -t <target>

Note: Prefix commands with npx/pnpx/yarn if nx isn't installed globally.

Core Commands

List and Explore Projects

# List all projects
nx show projects

# Filter by type, pattern, or target
nx show projects --type app
nx show projects --projects "apps/*"
nx show projects --withTarget build

# Find affected projects
nx show projects --affected --base=main

Get Project Information

Critical: Always use nx show project <name> --json for full resolved configuration. Do NOT read project.json directly - it contains only partial configuration.

# Get full configuration
nx show project my-app --json

# Extract targets
nx show project my-app --json | jq '.targets | keys'

Configuration schemas:

Workspace: node_modules/nx/schemas/nx-schema.json
Project: node_modules/nx/schemas/project-schema.json

Run Tasks

# Run specific project
nx build web --configuration=production

# Run affected
nx affected -t test --base=main

# View dependency graph
nx graph

Workspace Architecture

workspace/
├── apps/              # Deployable applications
├── libs/              # Shared libraries
│   ├── shared/        # Shared across scopes
│   └── feature/       # Feature-specific
├── nx.json            # Workspace configuration
└── tools/             # Custom executors/generators

Library Types

Type	Purpose	Example
feature	Business logic, smart components	`feature-auth`
ui	Presentational components	`ui-buttons`
data-access	API calls, state management	`data-access-users`
util	Pure functions, helpers	`util-formatting`

Detailed Resources

Configuration: See reference/configuration.md for:

nx.json templates and options
project.json structure
Module boundary rules
Remote caching setup

Commands: See reference/commands.md for:

Complete command reference
Advanced filtering options
Common workflows

CI/CD: See reference/ci-cd.md for:

GitHub Actions configuration
GitLab CI setup
Jenkins, Azure Pipelines, CircleCI examples
Affected commands in pipelines

Best Practices: See reference/best-practices.md for:

Do's and don'ts
Complete troubleshooting guide
Performance optimization
Migration guides

Common Workflows

"What's in this workspace?"

nx show projects --type app  # List applications
nx show projects --type lib  # List libraries

"How do I run project X?"

nx show project X --json | jq '.targets | keys'

"What changed?"

nx show projects --affected --base=main

Quick Troubleshooting

Targets not showing: Use nx show project <name> --json, not project.json
Affected not working: Ensure git history available (fetch-depth: 0 in CI)
Cache issues: Run nx reset

For detailed troubleshooting, see reference/best-practices.md.

Source

git clone https://github.com/tech-leads-club/agent-skills/blob/main/packages/skills-catalog/skills/(tooling)/nx-workspace/SKILL.md

View on GitHub

Overview

nx-workspace helps configure, explore, and optimize Nx monorepo workspaces. Use it when setting up Nx, exploring workspace structure, configuring project boundaries, analyzing affected projects, improving build caching, or implementing CI/CD with affected commands.

How This Skill Works

It leverages the Nx CLI to query and inspect workspace data. Core actions include listing projects with nx show projects, retrieving full project config via nx show project <name> --json, and identifying impacted work with nx show projects --affected or nx affected. It also supports dependency visualization with nx graph and is designed to be used with package managers like npx/pnpx/yarn when Nx is not globally installed.

When to Use It

Setting up a new Nx workspace and defining project boundaries
Exploring workspace structure to understand apps/libs organization
Analyzing which projects are affected by a change to optimize CI pipelines
Optimizing build caching and performance across the monorepo
Implementing CI/CD with affected commands to run only impacted projects

Quick Start

Step 1: Explore the workspace with nx show projects and nx show project <name> --json
Step 2: Check affected projects with nx show projects --affected --base=main
Step 3: Visualize or run an affected workflow with nx graph or nx affected -t <target> --base=main

Best Practices

Always use nx show project <name> --json for full resolved configuration
Use nx show projects --affected --base=main to identify impacted projects
Avoid reading project.json directly; rely on the outputs from nx show
Prefix CLI commands with npx/pnpx/yarn when Nx isn't installed globally
If you encounter cache issues, run nx reset to clear the local cache

Example Use Cases

List all projects in the workspace (apps/libs)
Get full configuration for my-app: nx show project my-app --json
Identify affected projects after merging main: nx show projects --affected --base=main
Run an affected test: nx affected -t test --base=main
Visualize the dependency graph: nx graph

Frequently Asked Questions

Add this skill to your agents