Nx Monorepo

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: ``bash npx create-nx-workspace@latest `` Follow prompts to select preset (Integrated, Standalone, Package-based) and framework stack.

1. Initialize Nx in an existing project: ``bash nx@latest init ``

1. Create with specific preset (non-interactive): ``bash 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: ``bash nx g @nx/react:app my-app ``

1. Generate a library: ```bash # 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: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