PipeCraft Example: Nx Monorepo

Advanced Nx monorepo demonstrating PipeCraft with mixed detection strategies.

Purpose

This example demonstrates:

• ✅ Nx integration - Automatic affected project detection
• ✅ Mixed detection - Nx projects + path-based domains working together
• ✅ Complex dependencies - 10+ libs with interdependencies, 4 apps
• ✅ Task dependencies - Respects Nx task graph (test WITH/WITHOUT build)
• ✅ Non-Nx code - Infrastructure and migrations as path-based domains
• ✅ 3-branch trunk flow - develop → staging → main
• ✅ Auto-merge enabled - Automatic promotion through all stages

Repository Structure

pipecraft-example-nx/
├── .github/workflows/
│   └── pipeline.yml          # Generated by PipeCraft
├── apps/
│   ├── frontend/             # Web frontend application
│   ├── backend/              # Backend API server
│   ├── widget/               # Embeddable widget
│   └── client/               # CLI client tool
├── libs/
│   ├── auth/                 # Authentication library
│   ├── database/             # Database layer
│   ├── logging/              # Logging utilities
│   ├── config/               # Configuration management
│   ├── user-management/      # User features
│   ├── analytics/            # Analytics tracking
│   ├── billing/              # Billing system
│   ├── notifications/        # Notification service
│   ├── reporting/            # Report generation
│   └── admin-dashboard/      # Admin dashboard
├── infra/
│   ├── pulumi/               # Infrastructure as Code (Pulumi)
│   └── kubernetes/           # Kubernetes manifests
├── migrations/
│   ├── 001-initial-schema/   # Database schema (pgroll)
│   └── 002-add-billing/      # Billing tables (pgroll)
├── nx.json                   # Nx configuration
├── .pipecraftrc.json         # PipeCraft configuration
└── package.json

Configuration

{
  "ciProvider": "github",
  "branchFlow": ["develop", "staging", "main"],
  "autoMerge": {
    "staging": true,
    "main": true
  },
  "domains": {
    "migrations": {
      "paths": ["migrations/**"],
      "description": "Database migrations (pgroll)"
    },
    "infra": {
      "paths": ["infra/**"],
      "description": "Infrastructure as code"
    }
  },
  "nx": {
    "enabled": true,
    "tasks": ["lint", "test", "build", "integration-test"],
    "baseRef": "origin/main"
  }
}

How It Works

Nx Affected Detection

When you change a file in libs/auth/, PipeCraft:

1. Runs nx show projects --affected to find impacted projects
2. Discovers that frontend, backend, and user-management depend on auth
3. Runs tests/builds for all affected projects automatically

Mixed Detection Strategy

Nx Projects (apps/ and libs/):

• Detected via nx show projects --affected
• Respects Nx dependency graph
• Uses Nx task dependencies (some libs need build before test)

Path-Based Domains (infra/ and migrations/):

• Detected via glob patterns: infra/**, migrations/**
• Not managed by Nx
• Run independently when their paths change

Example Scenarios

Scenario 1: Change a foundational library

# Edit libs/auth/src/index.ts
git add libs/auth/
git commit -m "feat: add OAuth support to auth"
git push origin develop

PipeCraft will:

• Detect affected projects: auth, user-management, admin-dashboard, frontend, backend
• Run tests for all 5 projects
• Run builds for all 5 projects
• Auto-promote to staging if tests pass
• Auto-promote to main with version tag

Scenario 2: Change infrastructure

# Edit infra/pulumi/index.ts
git add infra/
git commit -m "feat: add new load balancer"
git push origin develop

PipeCraft will:

• Detect infra domain changed
• Run infra tests (Pulumi preview)
• NOT run any Nx projects (nothing in apps/libs changed)
• Auto-promote through pipeline

Scenario 3: Change app + infrastructure

# Edit both frontend and infra
git add apps/frontend/ infra/
git commit -m "feat: deploy frontend to new infrastructure"
git push origin develop

PipeCraft will:

• Detect frontend via Nx affected
• Detect infra via path pattern
• Run tests for frontend (and its dependencies)
• Run tests for infra
• Auto-promote if all pass

Dependency Graph

Visual Representation

┌─────────────┐
│   frontend  │──┐
└─────────────┘  │
                 ├──► auth
┌─────────────┐  │
│   backend   │──┤
└─────────────┘  │
                 ├──► database ──► logging
┌─────────────┐  │
│   widget    │──┘
└─────────────┘

┌─────────────┐      ┌──────────┐
│ infra/**    │      │migrations│
└─────────────┘      └──────────┘
(path-based)         (path-based)

View full graph:

nx graph

Getting Started

Prerequisites

• Node.js 18+
• Git configured
• GitHub account

Clone and Setup

# Clone repository
git clone https://github.com/jamesvillarrubia/pipecraft-example-nx.git
cd pipecraft-example-nx

# Install dependencies
npm install

# View Nx graph
npm run graph

Run Tests Locally

# Run all tests
npm test

# Run affected tests
npm run affected:test

# Run specific project
npx nx test auth

Use as Template

1. Click "Use this template" on GitHub
2. Clone your repo
3. Customize:
   • Update nx.json with your project structure
   • Update .pipecraftrc.json domains
   • Add your apps and libs
4. Regenerate workflows:

   npx pipecraft generate

5. Push and test!

Workflow

Development

git checkout develop
git pull origin develop

# Make changes to any project
echo "export const newFeature = () => {}" >> libs/auth/src/index.ts

# Commit with conventional format
git add .
git commit -m "feat(auth): add new authentication feature"
git push origin develop

Automatic Pipeline

1. Nx Affected Analysis - Determines which projects changed
2. Parallel Testing - Runs tests for affected projects
3. Version Calculation - Calculates semantic version
4. Auto-Promote to Staging - Fast-forwards if tests pass
5. Auto-Promote to Main - Fast-forwards with version tag

Branch Flow

develop ───────────► staging ───────────► main
  │                     │                   │
  │  feat: new feature │                   │
  ├─────────────────────┤                   │
  │    auto-merge       │                   │
  └─────────────────────┼───────────────────┤
                        │   auto-merge      │
                        └───────────────────► v0.2.0

Task Dependencies

Default: Test WITHOUT Build

Most libraries don't need to be built before testing:

• auth, logging, config
• user-management, notifications
• reporting, admin-dashboard

Configured in nx.json:

{
  "targetDefaults": {
    "test": {
      "dependsOn": []
    }
  }
}

Exception: Test WITH Build

Some libraries require build artifacts:

• database - Compiled TypeScript for DB connections
• analytics - Built modules for event tracking
• billing - Compiled payment processing code

Configured in each project.json:

{
  "targets": {
    "test": {
      "dependsOn": ["build"]
    }
  }
}

Troubleshooting

Affected Detection Not Working

# Verify Nx can detect changes
npx nx show projects --affected --base=origin/main

# Check git history is available
git log --oneline -10

# Verify base branch exists
git fetch origin
git branch -r | grep main

Wrong Projects Running

1. Check Nx dependencies:

   nx graph

2. Verify project.json dependencies:

   {
     "implicitDependencies": ["shared-lib"]
   }

3. Check PipeCraft is using correct base: In workflow logs, look for:

   NX_BASE=origin/main npx nx show projects --affected
   

Infra/Migrations Not Running

1. Verify paths in .pipecraftrc.json:

   {
     "domains": {
       "infra": {
         "paths": ["infra/**"]  // Must match actual directory
       }
     }
   }

2. Test path detection locally:

   git diff --name-only origin/main | grep "infra/"

Advanced Topics

Custom Nx Tasks

Add custom tasks to PipeCraft config:

{
  "nx": {
    "tasks": ["lint", "test", "build", "e2e", "deploy"]
  }
}

Multiple Path-Based Domains

Add more non-Nx domains:

{
  "domains": {
    "infra": { "paths": ["infra/**"] },
    "migrations": { "paths": ["migrations/**"] },
    "docs": { "paths": ["docs/**"] },
    "scripts": { "paths": ["scripts/**"] }
  }
}

Conditional Task Execution

Some Nx projects might not have all tasks. PipeCraft handles this gracefully - if a task doesn't exist for a project, it's skipped.

Testing Suite

This repository includes an advanced test suite for validating PipeCraft's Nx integration. See:

• PIPECRAFT_INTEGRATION.md - Integration details
• TEST-SUITE-README.md - Test suite documentation
• TEST-REPORT.md - Latest test results

Run the test suite:

npm run test:pipecraft

Related Examples

• pipecraft-example-minimal - Simplest setup, quickstart
• pipecraft-example-basic - Multi-domain without Nx
• pipecraft-example-gated - Enterprise gated workflow

Learn More

• PipeCraft Documentation
• Nx Documentation
• Trunk-Based Development
• Conventional Commits

License

MIT © PipeCraft Team