nx-workspace Skill

1---2name: nx-workspace3description: "Explore and understand Nx workspaces. USE WHEN answering questions about the workspace, projects, or tasks. ALSO USE WHEN an nx command fails or you need to check available targets/configuration before running a task. EXAMPLES: 'What projects are in this workspace?', 'How is project X configured?', 'What depends on library Y?', 'What targets can I run?', 'Cannot find configuration for task', 'debug nx task failure'."4---5 6# Nx Workspace Exploration7 8This skill provides read-only exploration of Nx workspaces. Use it to understand workspace structure, project configuration, available targets, and dependencies.9 10Keep in mind that you might have to prefix commands with `npx`/`pnpx`/`yarn` if nx isn't installed globally. Check the lockfile to determine the package manager in use.11 12## Listing Projects13 14Use `nx show projects` to list projects in the workspace.15 16The project filtering syntax (`-p`/`--projects`) works across many Nx commands including `nx run-many`, `nx release`, `nx show projects`, and more. Filters support explicit names, glob patterns, tag references (e.g. `tag:name`), directories, and negation (e.g. `!project-name`).17 18```bash19# List all projects20nx show projects21 22# Filter by pattern (glob)23nx show projects --projects "apps/*"24nx show projects --projects "shared-*"25 26# Filter by tag27nx show projects --projects "tag:publishable"28nx show projects -p 'tag:publishable,!tag:internal'29 30# Filter by target (projects that have a specific target)31nx show projects --withTarget build32 33# Combine filters34nx show projects --type lib --withTarget test35nx show projects --affected --exclude="*-e2e"36nx show projects -p "tag:scope:client,packages/*"37 38# Negate patterns39nx show projects -p '!tag:private'40nx show projects -p '!*-e2e'41 42# Output as JSON43nx show projects --json44```45 46## Project Configuration47 48Use `nx show project <name> --json` to get the full resolved configuration for a project.49 50**Important**: Do NOT read `project.json` directly - it only contains partial configuration. The `nx show project --json` command returns the full resolved config including inferred targets from plugins.51 52You can read the full project schema at `node_modules/nx/schemas/project-schema.json` to understand nx project configuration options.53 54```bash55# Get full project configuration56nx show project my-app --json57 58# Extract specific parts from the JSON59nx show project my-app --json | jq '.targets'60nx show project my-app --json | jq '.targets.build'61nx show project my-app --json | jq '.targets | keys'62 63# Check project metadata64nx show project my-app --json | jq '{name, root, sourceRoot, projectType, tags}'65```66 67## Target Information68 69Targets define what tasks can be run on a project.70 71```bash72# List all targets for a project73nx show project my-app --json | jq '.targets | keys'74 75# Get full target configuration76nx show project my-app --json | jq '.targets.build'77 78# Check target executor/command79nx show project my-app --json | jq '.targets.build.executor'80nx show project my-app --json | jq '.targets.build.command'81 82# View target options83nx show project my-app --json | jq '.targets.build.options'84 85# Check target inputs/outputs (for caching)86nx show project my-app --json | jq '.targets.build.inputs'87nx show project my-app --json | jq '.targets.build.outputs'88 89# Find projects with a specific target90nx show projects --withTarget serve91nx show projects --withTarget e2e92```93 94## Workspace Configuration95 96Read `nx.json` directly for workspace-level configuration.97You can read the full project schema at `node_modules/nx/schemas/nx-schema.json` to understand nx project configuration options.98 99```bash100# Read the full nx.json101cat nx.json102 103# Or use jq for specific sections104cat nx.json | jq '.targetDefaults'105cat nx.json | jq '.namedInputs'106cat nx.json | jq '.plugins'107cat nx.json | jq '.generators'108```109 110Key nx.json sections:111 112- `targetDefaults` - Default configuration applied to all targets of a given name113- `namedInputs` - Reusable input definitions for caching114- `plugins` - Nx plugins and their configuration115- ...and much more, read the schema or nx.json for details116 117## Affected Projects118 119If the user is asking about affected projects, read the [affected projects reference](references/AFFECTED.md) for detailed commands and examples.120 121## Common Exploration Patterns122 123### "What's in this workspace?"124 125```bash126nx show projects127nx show projects --type app128nx show projects --type lib129```130 131### "How do I build/test/lint project X?"132 133```bash134nx show project X --json | jq '.targets | keys'135nx show project X --json | jq '.targets.build'136```137 138### "What depends on library Y?"139 140```bash141# Use the project graph to find dependents142nx graph --print | jq '.graph.dependencies | to_entries[] | select(.value[].target == "Y") | .key'143```144 145## Programmatic Answers146 147When processing nx CLI results, use command-line tools to compute the answer programmatically rather than counting or parsing output manually. Always use `--json` flags to get structured output that can be processed with `jq`, `grep`, or other tools you have installed locally.148 149### Listing Projects150 151```bash152nx show projects --json153```154 155Example output:156 157```json158["my-app", "my-app-e2e", "shared-ui", "shared-utils", "api"]159```160 161Common operations:162 163```bash164# Count projects165nx show projects --json | jq 'length'166 167# Filter by pattern168nx show projects --json | jq '.[] | select(startswith("shared-"))'169 170# Get affected projects as array171nx show projects --affected --json | jq '.'172```173 174### Project Details175 176```bash177nx show project my-app --json178```179 180Example output:181 182```json183{184  "root": "apps/my-app",185  "name": "my-app",186  "sourceRoot": "apps/my-app/src",187  "projectType": "application",188  "tags": ["type:app", "scope:client"],189  "targets": {190    "build": {191      "executor": "@nx/vite:build",192      "options": { "outputPath": "dist/apps/my-app" }193    },194    "serve": {195      "executor": "@nx/vite:dev-server",196      "options": { "buildTarget": "my-app:build" }197    },198    "test": {199      "executor": "@nx/vite:test",200      "options": {}201    }202  },203  "implicitDependencies": []204}205```206 207Common operations:208 209```bash210# Get target names211nx show project my-app --json | jq '.targets | keys'212 213# Get specific target config214nx show project my-app --json | jq '.targets.build'215 216# Get tags217nx show project my-app --json | jq '.tags'218 219# Get project root220nx show project my-app --json | jq -r '.root'221```222 223### Project Graph224 225```bash226nx graph --print227```228 229Example output:230 231```json232{233  "graph": {234    "nodes": {235      "my-app": {236        "name": "my-app",237        "type": "app",238        "data": { "root": "apps/my-app", "tags": ["type:app"] }239      },240      "shared-ui": {241        "name": "shared-ui",242        "type": "lib",243        "data": { "root": "libs/shared-ui", "tags": ["type:ui"] }244      }245    },246    "dependencies": {247      "my-app": [248        { "source": "my-app", "target": "shared-ui", "type": "static" }249      ],250      "shared-ui": []251    }252  }253}254```255 256Common operations:257 258```bash259# Get all project names from graph260nx graph --print | jq '.graph.nodes | keys'261 262# Find dependencies of a project263nx graph --print | jq '.graph.dependencies["my-app"]'264 265# Find projects that depend on a library266nx graph --print | jq '.graph.dependencies | to_entries[] | select(.value[].target == "shared-ui") | .key'267```268 269## Troubleshooting270 271### "Cannot find configuration for task X:target"272 273```bash274# Check what targets exist on the project275nx show project X --json | jq '.targets | keys'276 277# Check if any projects have that target278nx show projects --withTarget target279```280 281### "The workspace is out of sync"282 283```bash284nx sync285nx reset  # if sync doesn't fix stale cache286```287