/nx-monorepo

name: nx-monorepo
description: Provides comprehensive Nx monorepo management guidance for TypeScript/JavaScript projects. Use when creating Nx workspaces, generating apps/libraries/components, running affected commands, setting up CI/CD, configuring Module Federation, or implementing NestJS backends within Nx
allowed-tools: Read, Write, Edit, Bash, Glob, Grep

Nx Monorepo

Overview

Provides guidance for Nx monorepo management in TypeScript/JavaScript projects. Covers workspace creation, project generation, task execution, caching strategies, Module Federation, and CI/CD integration.

When to Use

Use this skill when:

• Creating a new Nx workspace or initializing Nx in an existing project
• Generating applications, libraries, or components with Nx generators
• Running affected commands or executing tasks across multiple projects
• Setting up CI/CD pipelines for Nx projects (GitHub Actions, CircleCI, etc.)
• Configuring Module Federation with React or Next.js
• Implementing NestJS backend applications within Nx
• Managing TypeScript package libraries with buildable and publishable libs
• Setting up remote caching or Nx Cloud
• Optimizing monorepo build times and caching strategies
• Debugging dependency graph issues or circular dependencies

**Trigger phrases:** "create Nx workspace", "Nx monorepo", "generate Nx app", "Nx affected", "Nx CI/CD", "Module Federation Nx", "Nx Cloud"

Instructions

Workspace Creation

1. **Create a new workspace with interactive setup:**

   npx create-nx-workspace@latest

Follow prompts to select preset (Integrated, Standalone, Package-based) and framework stack.

2. **Initialize Nx in an existing project:**

   nx@latest init

3. **Create with specific preset (non-interactive):**

   npx create-nx-workspace@latest my-workspace --preset=react

**Verify:** `nx show projects` lists the new workspace projects

Project Generation

1. **Generate a React application:**

   nx g @nx/react:app my-app

2. **Generate a library:**

   # React library
   nx g @nx/react:lib my-lib

   # TypeScript library
   nx g @nx/js:lib my-util

**Verify:** `nx show projects` lists the new lib

3. **Generate a component in lib:**

   nx g @nx/react:component my-comp --project=my-lib

4. **Generate NestJS backend:**

   nx g @nx/nest:app my-api

**Verify:** `nx show projects` lists `my-api` and `nx run my-api:build` succeeds

Task Execution

1. **Run tasks for affected projects only:**

   nx affected -t lint test build

2. **Run tasks across all projects:**

   # Build all projects
   nx run-many -t build

   # Test specific projects
   nx run-many -t test -p=my-app,my-lib

   # Test by pattern
   nx run-many -t test --projects=*-app

3. **Run specific target on single project:**

   nx run my-app:build

4. **Visualize dependency graph:**

   nx graph

Project Configuration

Each project has a `project.json` defining targets, executor, and configurations:

{
  "name": "my-app",
  "projectType": "application",
  "sourceRoot": "apps/my-app/src",
  "targets": {
    "build": {
      "executor": "@nx/react:webpack",
      "outputs": ["{workspaceRoot}/dist/apps/my-app"],
      "configurations": {
        "production": {
          "optimization": true
        }
      }
    },
    "test": {
      "executor": "@nx/vite:test"
    }
  },
  "tags": ["type:app", "scope:frontend"]
}

Dependency Management

1. **Set up project dependencies:**

   {
     "targets": {
       "build": {
         "dependsOn": [
           { "projects": ["shared-ui"], "target": "build" }
         ]
       }
     }
   }

2. **Use tags for organization:**

   { "tags": ["type:ui", "scope:frontend", "platform:web"] }

Module Federation (Nx 17+)

1. **Generate a remote (micro-frontend):**

   nx g @nx/react:remote checkout --host=dashboard

2. **Generate a host:**

   nx g @nx/react:host dashboard

CI/CD Setup

Use affected commands in CI to only build/test changed projects:

# .github/workflows/ci.yml
- run: npx nx affected -t lint --parallel
- run: npx nx affected -t test --parallel
- run: npx nx affected -t build --parallel

Examples

Example 1: Create New React Workspace

**Input:** "Create a new Nx workspace with React and TypeScript"

**Steps:**

npx create-nx-workspace@latest my-workspace
# Select: Integrated Monorepo → React → Integrated monorepo (Nx Cloud)

**Verify:** `cd my-workspace && nx show projects` lists the created app

**Expected Result:** Workspace created with:

• `apps/` directory with React app
• `libs/` directory for shared libraries
• `nx.json` with cache configuration
• CI/CD workflow files ready

Example 2: Run Tests for Changed Projects

**Input:** "Run tests only for projects affected by recent changes"

**Command:**

nx affected -t test --base=main~1 --head=main

**Expected Result:** Only tests for projects affected by changes between commits are executed, leveraging cached results from previous runs.

Example 3: Generate and Build a Shared Library

**Input:** "Create a shared UI library and use it in the app"

**Steps:**

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

# Generate component in library
nx g @nx/react:component button --project=shared-ui

# Import in app (tsconfig paths auto-configured)
import { Button } from '@my-workspace/shared-ui'

**Verify:** `nx run shared-ui:build` completes successfully and `nx graph` shows the dependency link to your app

**Expected Result:** Buildable library at `libs/shared-ui` with proper TypeScript path mapping configured.

Example 4: Set Up Module Federation

**Input:** "Configure Module Federation for micro-frontends"

**Steps:**

# Create host app
nx g @nx/react:ho