Claude Code और Nx Workspace: Monorepo की व्यावहारिक गाइड

Nx Workspace बड़ा repository नहीं, boundaries की map है

अगर आप Claude Code से सिर्फ “monorepo बना दो” कहेंगे, तो वह कई files बना देगा। असली समस्या बाद में आती है: क्या apps/web की change apps/admin को तोड़ेगी? Button app में रहना चाहिए या shared UI library में? क्या CI को हर pull request पर सभी tests चलाने चाहिए?

Nx Workspace इन सवालों का जवाब project graph, task graph, affected commands और cache से देता है। आधिकारिक Nx mental model बताता है कि Nx projects को analyze करके केवल जरूरी काम चलाता है। शुरुआती लोगों के लिए सरल भाषा में: Nx dependency map और task runner का संयोजन है।

इस guide में Claude Code को unchecked generator नहीं, बल्कि reviewer और pair programmer की तरह इस्तेमाल किया गया है। official docs खुले रखें: create-nx-workspace, workspace generators, affected, CI setup, और caching tasks। साथ में Claude Code monorepo management, pnpm workspace, और CI/CD setup भी पढ़ें।

---

Nx कब सच में काम आता है

Nx हर छोटे project के लिए जरूरी नहीं है। एक landing page और छोटी API के लिए simple repository बेहतर हो सकती है। Nx तब काम आता है जब boundaries और verification cost भारी होने लगती है।

पहला real use case है: कई apps एक ही types या UI share करती हैं। उदाहरण के लिए apps/web, apps/admin, apps/api, libs/contracts, और libs/ui को साथ रखकर API types और UI primitives एक ही PR में update किए जा सकते हैं।

दूसरा use case है selective CI। अगर content site, training pages, admin tool और API एक ही repo में हैं, तो हर PR पर पूरा build चलाना slow होगा। nx affected -t test build Git changes और dependency graph देखकर सिर्फ affected projects चुनता है।

तीसरा use case है Claude Code को safer बनाना। जब libs/ui सिर्फ UI, libs/contracts API types, libs/config shared tooling और apps/* deployable apps हों, तो Claude Code की suggestions छोटी रहती हैं। AdSense, affiliate links, consultation forms या payment CTA वाली pages में यह revenue safety देता है।

अगर आप अभी repository boundaries explain नहीं कर पा रहे हैं, तो पहले repo map first pass करें। Nx clear structure को तेज करता है; unclear structure को अपने आप सही नहीं करता।

---

Target workspace

यह tutorial छोटा workspace बनाता है: दो React apps, एक Node API, एक UI library, एक contracts library और एक config library।

flowchart LR
  web["apps/web\nReact + Vite"] --> ui["libs/ui\nUI primitives"]
  admin["apps/admin\nReact + Vite"] --> ui
  web --> contracts["libs/contracts\nAPI types"]
  admin --> contracts
  api["apps/api\nNode API"] --> contracts
  web --> config["libs/config\nlint/test config"]
  api --> config

Rule simple है। apps/* run या deploy होने वाली units हैं। libs/* reusable parts हैं। Library को app से import नहीं करना चाहिए। UI library API environment variables नहीं पढ़ती, और contracts library React components नहीं रखती।

Claude Code को edit से पहले boundary दें:

पहले इस Nx Workspace को समझें। अभी files edit न करें।

Rules:
- apps/web और apps/admin frontend apps हैं
- apps/api API है
- libs/ui में केवल reusable UI components हैं
- libs/contracts में API types और Zod schemas हैं
- libs/config में shared ESLint, Vitest और TypeScript config है
- libs/* को apps/* से import नहीं करना है

Change से पहले nx graph देखें। Change के बाद verification के लिए nx affected commands दें।

---

Copy-paste setup

Commands मानते हैं कि Node.js 20+, Git और pnpm installed हैं। Options explicit रखे गए हैं ताकि interactive prompts पर निर्भरता न रहे।

npx create-nx-workspace@latest acme-nx \
  --workspaceType=integrated \
  --preset=apps \
  --packageManager=pnpm \
  --nxCloud=skip \
  --interactive=false

cd acme-nx
pnpm nx add @nx/react
pnpm nx add @nx/node

Apps और libraries Nx generators से बनाएं। Generator folders के साथ Nx config, TypeScript paths और project metadata भी consistent रखता है।

pnpm nx g @nx/react:app web \
  --directory=apps/web \
  --bundler=vite \
  --unitTestRunner=vitest \
  --e2eTestRunner=playwright \
  --style=css

pnpm nx g @nx/react:app admin \
  --directory=apps/admin \
  --bundler=vite \
  --unitTestRunner=vitest \
  --e2eTestRunner=none \
  --style=css

pnpm nx g @nx/node:app api \
  --directory=apps/api \
  --unitTestRunner=vitest

pnpm nx g @nx/react:lib ui \
  --directory=libs/ui \
  --unitTestRunner=vitest

pnpm nx g @nx/js:lib contracts \
  --directory=libs/contracts \
  --unitTestRunner=vitest

pnpm nx g @nx/js:lib config \
  --directory=libs/config \
  --unitTestRunner=none

Edit करने से पहले result देखें:

pnpm nx graph
pnpm nx show projects
pnpm nx show project web

अगर graph पहले से tangled दिखे, तो नई libraries जोड़ने से पहले structure सरल करें।

---

project.json पहले पढ़ें

Beginners के लिए project.json किसी project की runnable jobs की list है।

{
  "name": "web",
  "sourceRoot": "apps/web/src",
  "projectType": "application",
  "targets": {
    "build": {
      "executor": "@nx/vite:build",
      "outputs": ["{options.outputPath}"],
      "options": {
        "outputPath": "dist/apps/web"
      }
    },
    "test": {
      "executor": "@nx/vite:test",
      "outputs": ["{workspaceRoot}/coverage/apps/web"],
      "options": {
        "passWithNoTests": true
      }
    },
    "serve": {
      "executor": "@nx/vite:dev-server",
      "options": {
        "buildTarget": "web:build"
      }
    }
  },
  "tags": ["scope:app", "type:web"]
}

Claude Code से पहले explanation मांगें:

apps/web/project.json पढ़कर build, test और serve को beginner-friendly तरीके से समझाएं।
अगर change जरूरी हो, तो केवल सबसे छोटा diff propose करें।
outputs, cache behavior और dependsOn relations न तोड़ें।

outputs cache के लिए जरूरी है। गलत path cache को बेकार बना सकता है या पुराने artifacts reuse करवा सकता है।

---

CI में affected लगाएं

affected Git changes और project graph compare करके केवल impacted projects पर tasks चलाता है।

pnpm nx affected -t lint test build --base=main --head=HEAD
pnpm nx affected:graph --base=main --head=HEAD

GitHub Actions में full history fetch करें ताकि branch comparison काम करे। Tasks को nx के through चलाएं; direct vitest, eslint या tsc calls Nx cache और affected logic bypass कर देती हैं।

name: nx-ci

on:
  pull_request:
  push:
    branches: [main]

jobs:
  affected:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: pnpm/action-setup@v4
        with:
          version: 10
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: pnpm
      - run: pnpm install --frozen-lockfile
      - run: pnpm nx affected -t lint test build --base=origin/main --head=HEAD --parallel=3

Teams के लिए Nx Cloud remote cache मदद कर सकता है। शुरुआत में local cache और affected से value prove करें, फिर CI time bottleneck बनने पर remote cache जोड़ें।

---

Common failure cases

पहली गलती है libs/shared बनाकर सब कुछ उसमें डालना। Code move करने से पहले Claude Code से पूछें कि यह UI, contracts, config या pure utility में से क्या है।

दूसरी गलती है libs/* से apps/* import करना। इससे dependency direction उलट जाती है और library reusable नहीं रहती।

तीसरी गलती है CI में raw tools चलाना। pnpm nx run-many -t test या pnpm nx affected -t test को prefer करें।

चौथी गलती है पहले week में over-engineering। Real duplication से पहले libs/auth, libs/domain, libs/data-access न बनाएं।

पांचवीं गलती है Claude Code को graph context के बिना edit करने देना। Prompt में work से पहले pnpm nx graph और बाद में pnpm nx affected -t test build जोड़ें।

---

Monetization angle: revenue pages को बचाएं

ClaudeCodeLab जैसे site में articles, training pages, admin, lead forms और analytics एक ही repo में हो सकते हैं। Nx सिर्फ speed नहीं देता; वह बताता है कि revenue page affected है या नहीं। libs/cta बदलता है तो graph दिखाता है किन pages को review करना है। libs/analytics बदलता है तो affected CI बताता है किन apps पर smoke test चाहिए।

यह AdSense layouts, affiliate blocks, checkout CTAs और consultation forms के लिए उपयोगी है। Team में Claude Code और monorepo workflow standardize करना हो तो ClaudeCodeLab training देखें। अकेले सीख रहे हैं तो पहले यह sample workspace बनाएं और nx graph का screenshot रखें।

Hands-on verification

Masa के रूप में test करते समय मैंने पहले केवल web, admin, api, ui और contracts बनाए। libs/contracts में type change करने पर pnpm nx affected -t test build --base=main --head=HEAD ने contracts पर depend करने वाली apps चुनीं। सिर्फ libs/ui बदलने पर API build scope से बाहर रहा। मुख्य सीख यह थी कि Nx options याद करना जरूरी नहीं; graph और boundaries पहले visible कर दें, फिर Claude Code की changes छोटी और reviewable रहती हैं।

Summary

Nx Workspace repository को बड़ा बनाने के लिए नहीं है। यह dependencies visible करता है, सिर्फ affected projects verify करता है, और Claude Code को clear boundaries देता है।

छोटे से शुरू करें, project.json पढ़ें, nx graph देखें, और nx affected को CI में डालें। इसके बाद Claude Code file generator से आगे बढ़कर monorepo structure का useful reviewer बनता है।