Claude Code से Monorepo प्रबंधन: pnpm, Turborepo, Nx और CI

Monorepo वह संरचना है जिसमें कई applications और libraries एक ही Git repository में रखी जाती हैं। इससे apps/web, apps/api, packages/ui, packages/shared जैसे हिस्सों में types, UI, configuration और CI rules साझा करना आसान होता है। लेकिन boundaries साफ नहीं हों तो Claude Code अनजाने में बहुत बड़ा बदलाव कर सकता है, और एक shared package की छोटी सी edit कई apps को प्रभावित कर सकती है।

सुरक्षित workflow यह है: पहले Claude Code से repo map बनवाएं, फिर package boundaries तय करें, internal dependencies को pnpm workspace और workspace:* से बांधें, और Turborepo या Nx के affected tasks से केवल बदले हुए हिस्सों पर lint, test, build चलाएं। Official concepts के लिए Nx why monorepos, Nx affected, Nx mental model, pnpm और Turborepo docs उपयोगी हैं।

लक्ष्य संरचना

Code edit शुरू करने से पहले structure समझना जरूरी है।

graph TD
  WEB["apps/web"] --> UI["packages/ui"]
  WEB --> SHARED["packages/shared"]
  API["apps/api"] --> SHARED
  UI --> CONFIG["packages/config"]
  SHARED --> CONFIG
  CI["CI affected tasks"] --> WEB
  CI --> API

apps/* deploy होने वाली applications हैं। packages/* reusable modules हैं। Package boundary का मतलब है कि कौन सा package किस दूसरे package पर depend कर सकता है। Claude Code को यह rule साफ शब्दों में देना चाहिए।

Claude Code के लिए पहला prompt

इस repository को monorepo की तरह analyze करें।

Assumptions:
- apps/web Next.js application है
- apps/api API server है
- packages/ui reusable UI है
- packages/shared में types, validations और pure functions हैं
- packages/config में ESLint, TypeScript, Prettier और test config है

Rules:
- apps/* सीधे apps/* पर depend नहीं करेगा
- packages/* apps/* पर depend नहीं करेगा
- internal packages workspace:* versions इस्तेमाल करेंगे
- बदलाव के बाद lint/test/build affected tasks से verify होंगे

पहले repo map दें: dependencies, risky cycles, ज्यादा shared files, और CI commands.
अभी files edit न करें।

आखिरी line बहुत जरूरी है। Monorepo में असली risk अक्सर syntax error नहीं, बल्कि dependency direction होता है।

pnpm workspace setup

packages:
  - "apps/*"
  - "packages/*"

Root package.json में standard commands रखें।

{
  "name": "acme-monorepo",
  "private": true,
  "packageManager": "pnpm@10.12.1",
  "scripts": {
    "build": "turbo run build",
    "lint": "turbo run lint",
    "test": "turbo run test",
    "typecheck": "turbo run typecheck",
    "ci:affected": "turbo run lint test build --affected",
    "check:deps": "node scripts/check-workspace-deps.cjs"
  }
}

Internal dependency इस तरह लिखें:

{
  "dependencies": {
    "@acme/shared": "workspace:*",
    "@acme/ui": "workspace:*"
  }
}

Claude Code को request करते समय policy भी लिखें।

apps/web में @acme/ui और @acme/shared usable बनाएं।
package.json में workspace:* इस्तेमाल करें।
../../packages वाले relative imports न बनाएं।
बदलाव pnpm check:deps और pnpm ci:affected से verify हो सके।

Turborepo और Nx affected

Turborepo तब अच्छा है जब packages में scripts पहले से मौजूद हों।

{
  "$schema": "https://turbo.build/schema.json",
  "tasks": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": ["dist/**", ".next/**", "!.next/cache/**"]
    },
    "lint": {
      "dependsOn": ["^build"]
    },
    "test": {
      "dependsOn": ["^build"],
      "outputs": ["coverage/**"]
    },
    "typecheck": {
      "dependsOn": ["^build"]
    },
    "dev": {
      "cache": false,
      "persistent": true
    }
  }
}

Nx तब उपयोगी है जब project graph और impact analysis ज्यादा मजबूत चाहिए।

pnpm dlx nx@latest init
pnpm nx affected -t lint test build --base=origin/main --head=HEAD

Claude Code को “सब कुछ चलाओ” कहने के बजाय “इस diff से affected checks चलाओ” कहना बेहतर है।

CODEOWNERS और dependency policy

/apps/web/ @acme/frontend
/apps/api/ @acme/backend
/packages/ui/ @acme/design-system
/packages/shared/ @acme/platform
/packages/config/ @acme/platform
/pnpm-workspace.yaml @acme/platform
/turbo.json @acme/platform

Policy को code से भी check करें। इसे scripts/check-workspace-deps.cjs में रखें।

const fs = require("node:fs");
const path = require("node:path");

const ROOT = process.cwd();
const WORKSPACE_DIRS = ["apps", "packages"];
const DEP_FIELDS = ["dependencies", "devDependencies", "peerDependencies", "optionalDependencies"];

function readJson(file) {
  return JSON.parse(fs.readFileSync(file, "utf8"));
}

function findPackageDirs(baseDir) {
  const absoluteBase = path.join(ROOT, baseDir);
  if (!fs.existsSync(absoluteBase)) return [];
  return fs
    .readdirSync(absoluteBase, { withFileTypes: true })
    .filter((entry) => entry.isDirectory())
    .map((entry) => path.join(absoluteBase, entry.name))
    .filter((dir) => fs.existsSync(path.join(dir, "package.json")));
}

const packages = WORKSPACE_DIRS.flatMap(findPackageDirs).map((dir) => {
  const manifest = readJson(path.join(dir, "package.json"));
  return { dir, name: manifest.name, manifest };
});

const byName = new Map(packages.map((pkg) => [pkg.name, pkg]));
let failed = false;

for (const pkg of packages) {
  for (const field of DEP_FIELDS) {
    const deps = pkg.manifest[field] || {};
    for (const [name, range] of Object.entries(deps)) {
      const internal = byName.get(name);
      if (!internal) continue;
      const fromDir = path.relative(ROOT, pkg.dir).replace(/\\/g, "/");
      const toDir = path.relative(ROOT, internal.dir).replace(/\\/g, "/");

      if (!String(range).startsWith("workspace:")) {
        console.error(`${pkg.name}: ${name} must use workspace:* in ${field}`);
        failed = true;
      }
      if (toDir.startsWith("apps/")) {
        console.error(`${pkg.name}: ${fromDir} must not depend on app package ${toDir}`);
        failed = true;
      }
    }
  }
}

if (failed) process.exit(1);
console.log(`Checked ${packages.length} workspace packages.`);

CI checklist

name: monorepo-ci

on:
  pull_request:
  push:
    branches: [main]

jobs:
  checks:
    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: 22
          cache: pnpm
      - run: pnpm install --frozen-lockfile
      - run: pnpm check:deps
      - run: pnpm ci:affected

fetch-depth: 0 जरूरी है, क्योंकि affected checks Git history पर निर्भर करते हैं।

Practical use cases

1. packages/ui में Button का loading state जोड़ना। Claude Code से public API stable रखने और apps/web में affected screens बताने को कहें।

2. API और frontend के shared DTOs को packages/shared में ले जाना। DTO data transfer shape है; database model नहीं।

3. TypeScript, Next.js या testing tools upgrade करना। पहले packages/config बदलें, फिर affected apps verify करें।

4. Billing, search या onboarding जैसी cross-team feature को छोटे PRs में बांटना। Claude Code से पहले PR split plan बनवाएं।

आम pitfalls

पहला, packages/shared को हर चीज का folder बना देना। इसमें केवल stable, generic और testable code होना चाहिए।

दूसरा, ../../packages/shared/src जैसे relative imports। ये package boundary तोड़ते हैं।

तीसरा, Turborepo और Nx दोनों को एक साथ गहराई से अपनाना। पहले एक main model चुनें।

चौथा, “local पर चल गया” को पर्याप्त मान लेना। PR में changed packages, affected apps, executed commands और remaining risk लिखना चाहिए।

Review prompt

इस diff को monorepo perspective से review करें।

Check:
- apps/* से apps/* direct dependency नहीं है
- packages/* से apps/* dependency नहीं है
- internal dependencies workspace:* हैं
- packages/shared में केवल stable shared code है
- affected lint/test/build पर्याप्त है
- CODEOWNERS review responsibility साफ है

Return:
- blockers
- recommended fixes
- verified commands
- PR body के लिए impact summary

आगे पढ़ें: Claude Code और Nx workspace, Claude Code और pnpm workspace, Claude Code with Turborepo, Claude Code team collaboration।

अगर आपकी team Claude Code को real monorepo में introduce कर रही है, तो tooling से पहले boundaries, owners, CI और review prompts तय करें। ClaudeCodeLab की Claude Code training और consultation में real repository के आधार पर CLAUDE.md, CODEOWNERS, CI और PR workflow design किया जा सकता है।

सारांश

Claude Code monorepo में तब सबसे अच्छा काम करता है जब constraints स्पष्ट हों। Repo map, package boundaries, pnpm workspace, Turborepo/Nx affected tasks, CODEOWNERS, dependency policy और CI checklist AI output को repeatable engineering workflow बनाते हैं। Practice में workspace:* enforce करना और pnpm ci:affected standard बनाना review misses और unnecessary full CI को कम करता है।