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

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

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

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

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)

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