Nx Monorepo

Overview

When to Use

• 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

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.
2. Initialize Nx in an existing project:
   bash

   nx@latest init

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

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

Project Generation

1. Generate a React application:
   bash

   nx g @nx/react:app my-app

2. Generate a library:
   bash

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

3. Generate a component in lib:
   bash

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

4. Generate NestJS backend:
   bash

   nx g @nx/nest:app my-api

Task Execution

1. Run tasks for affected projects only:
   bash

   nx affected -t lint test build

2. Run tasks across all projects:
   bash

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

   nx run my-app:build

4. Visualize dependency graph:
   bash

   nx graph

Project Configuration

project.json

{
  "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:
   json

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

2. Use tags for organization:
   json

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

Module Federation (Nx 17+)

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

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

2. Generate a host:
   bash

   nx g @nx/react:host dashboard

CI/CD Setup

# .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

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

• 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

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

Example 3: Generate and Build a Shared Library

# 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'

libs/shared-ui

Example 4: Set Up Module Federation

# 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

Example 5: Debug Build Dependencies

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

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

namedInputs

nx.json

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