Nx Monorepo

Overview

Provides comprehensive guidance for working with Nx monorepos in TypeScript/JavaScript projects. Nx is a smart build system with advanced caching, affected command execution, and powerful generators for React, Next.js, NestJS, and more. This skill 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
   

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
   

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
   

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)

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'

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:host dashboard

# Add remote to host
nx g @nx/react:remote product-catalog --host=dashboard

# Start dev servers
nx run dashboard:serve
nx run product-catalog:serve

Expected Result: Two separate applications running where product-catalog loads dynamically into dashboard at runtime.

Example 5: Debug Build Dependencies

Input: "Why is my app rebuilding when unrelated lib changes?"

Diagnosis:

# Show project graph
nx graph --focused=my-app

# Check implicit dependencies
nx show project my-app --json | grep implicitDependencies

Solution: Add explicit dependency configuration or use namedInputs in nx.json to exclude certain files from triggering builds.

Best Practices

• Always use nx affected in CI to only test/build changed projects
• Organize libs by domain/business capability, not by technical layer
• Use tags consistently (type:app|lib, scope:frontend|backend|shared)
• Prevent circular dependencies by configuring workspaceLayout boundaries in nx.json
• Enable remote caching with Nx Cloud for team productivity
• Keep project.json simple - use defaults from nx.json when possible
• Leverage generators instead of manual file creation for consistency
• Configure namedInputs to exclude test files from production cache keys
• Use Module Federation for independent deployment of micro-frontends
• Keep workspace generators in tools/ for project-specific scaffolding

Constraints and Warnings

• Node.js 18.10+ is required for Nx 17+
• Windows users: Use WSL or Git Bash for best experience
• First-time setup may take longer due to package installation
• Large monorepos (50+ projects) should use distributed task execution
• Module Federation requires webpack 5+ and specific Nx configuration
• Some generators require additional plugins to be installed first
• Cache location: Default ~/.nx/cache can grow large; configure cacheDirectory in nx.json if needed
• Circular dependencies will cause build failures; use nx graph to visualize
• Preset migration: Converting between Integrated/Standalone/Package-based requires manual effort

Reference Files

For detailed guidance on specific topics, consult:

Topic	Reference File
Workspace setup, basic commands	references/basics.md
Generators (app, lib, component)	references/generators.md
React, Next.js, Expo patterns	references/react.md
NestJS backend patterns	references/nestjs.md
TypeScript packages	references/typescript.md
CI/CD (GitHub, CircleCI, etc.)	references/ci-cd.md
Caching, affected, advanced	references/advanced.md