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

-

Create a new workspace with interactive setup:

npx create-nx-workspace@latest

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

-

Initialize Nx in an existing project:

nx@latest init

-

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

-

Generate a React application:

nx g @nx/react:app my-app

-

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

-

Generate a component in lib:

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

-

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

-

Run tasks for affected projects only:

nx affected -t lint test build

-

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

-

Run specific target on single project:

nx run my-app:build

-

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

-

Set up project dependencies:

{

  "targets": {

    "build": {

      "dependsOn": [

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

      ]

    }

  }

}

-

Use tags for organization:

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

Module Federation (Nx 17+)

-

Generate a remote (micro-frontend):

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

-

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

Verify: Both servers start without errors and nx graph shows dashboard → product-catalog remote connection

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.

Verify Fix Worked: Make a change to the unrelated lib, run nx affected -t build — my-app should not appear in the affected projects list.

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