Skip to content

giuseppe-trisciuoglio/developer-kit / plugins/developer-kit-typescript/skills/nx-monorepo

nx-monorepo

Verified

Provides comprehensive Nx monorepo management guidance for TypeScript/JavaScript projects. Use when creating Nx workspaces, generating apps/libraries/components, running affected commands, setting up CI/CD, configuring Module Federation, or implementing NestJS backends within Nx

FileKindSize
SKILL.mdskill md8.9 KB
references/advanced.mdmarkdown7.4 KB
references/basics.mdmarkdown3.9 KB
references/ci-cd.mdmarkdown7.8 KB
references/generators.mdmarkdown5.2 KB
references/nestjs.mdmarkdown7.1 KB
references/react.mdmarkdown6.3 KB
references/typescript.mdmarkdown6.8 KB
---
name: nx-monorepo
description: Provides comprehensive Nx monorepo management guidance for TypeScript/JavaScript projects. Use when creating Nx workspaces, generating apps/libraries/components, running affected commands, setting up CI/CD, configuring Module Federation, or implementing NestJS backends within Nx
allowed-tools: Read, Write, Edit, Bash, Glob, Grep
---

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

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
   ```
   **Verify:** `nx show projects` lists the new workspace projects

### 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
   ```
   **Verify:** `nx show projects` lists the new lib

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
   ```
   **Verify:** `nx show projects` lists `my-api` and `nx run my-api:build` succeeds

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

Each project has a `project.json` defining targets, executor, and configurations:

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

Use affected commands in CI to only build/test changed projects:

```yaml
# .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:**
```bash
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:**
```bash
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:**
```bash
# 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:**
```bash
# 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:**
```bash
# 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](references/basics.md) |
| Generators (app, lib, component) | [references/generators.md](references/generators.md) |
| React, Next.js, Expo patterns | [references/react.md](references/react.md) |
| NestJS backend patterns | [references/nestjs.md](references/nestjs.md) |
| TypeScript packages | [references/typescript.md](references/typescript.md) |
| CI/CD (GitHub, CircleCI, etc.) | [references/ci-cd.md](references/ci-cd.md) |
| Caching, affected, advanced | [references/advanced.md](references/advanced.md) |
writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deploymentStars: 322kUpdated Claude CodeCodexVerifiedInstall
xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy.Stars: 119kUpdated Claude CodeCodexVerifiedInstall
childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release.Stars: 118kUpdated Claude CodeCodexVerifiedInstall