Claude Code और Turborepo से तेज Monorepo Build

Claude Code और Turborepo साथ क्यों काम आते हैं

Monorepo में कई apps और shared packages एक ही repository में रखे जाते हैं। शुरुआत में apps/web और packages/ui काफी लगते हैं, लेकिन जैसे ही admin app, docs site, shared utilities और अलग-अलग deployments जुड़ते हैं, build order, package boundaries, CI time और cache policy मुश्किल हो जाते हैं।

Turborepo task graph और cache से यह काम संभालता है। Claude Code तब सबसे उपयोगी होता है जब आप उसे सिर्फ config generator नहीं, बल्कि repository reviewer की तरह इस्तेमाल करते हैं। वह package.json पढ़ सकता है, packages के बीच dependency समझा सकता है, missing outputs ढूंढ सकता है, और CI को affected packages तक सीमित करने का सुझाव दे सकता है।

यह लेख 2 जून 2026 के Turborepo v2 को आधार मानता है। turbo.json में पुराना pipeline नहीं, बल्कि tasks इस्तेमाल करें। लागू करने से पहले official docs देखें: Turborepo configuration, turbo run, Remote Caching, और Claude Code memory।

आगे पढ़ने के लिए monorepo management, pnpm workspace with Claude Code, और Claude Code CI/CD setup देखें।

लक्ष्य संरचना और तीन उपयोग के मामले

यहां लक्ष्य एक छोटा TypeScript monorepo है जो pnpm workspace पर चलता है। शुरुआत में छोटे और साफ packages रखना बेहतर है, क्योंकि Claude Code स्पष्ट सीमाओं को shared या common जैसे अस्पष्ट नामों से बेहतर समझता है।

flowchart LR
  web["apps/web\nCustomer app"] --> ui["packages/ui\nShared UI"]
  admin["apps/admin\nAdmin app"] --> ui
  web --> utils["packages/utils\nShared functions"]
  admin --> utils
  ui --> tsconfig["packages/tsconfig\nTS config"]
  utils --> tsconfig

पहला उपयोग मामला है customer app और admin app में समान buttons, forms और validators का उपयोग। packages/ui और packages/utils अलग रखने से Claude Code visual components और business utilities को मिलाने की गलती कम करता है।

दूसरा उपयोग मामला content या documentation platform है। Landing page, docs और internal dashboard एक repository में हों तो हर PR पर पूरी CI चलाना महंगा हो जाता है। --affected और --filter सिर्फ बदले हुए packages और उनसे प्रभावित packages को चलाने में मदद करते हैं।

तीसरा उपयोग मामला SaaS है जहां pricing, signup, account settings और admin flows revenue से जुड़े होते हैं। यदि lint, type-check, test और build स्थिर हैं, तो Claude Code CTA या onboarding बदल सकता है और CI फिर भी shared code टूटने पर रोक लगाएगी।

न्यूनतम repository structure

पहले directory shape तय करें। ज्यादा packages बनाने से अधिक जरूरी है कि हर package की जिम्मेदारी एक वाक्य में समझाई जा सके।

acme-monorepo/
  apps/
    web/
      package.json
      src/
    admin/
      package.json
      src/
  packages/
    ui/
      package.json
      src/
    utils/
      package.json
      src/
    tsconfig/
      package.json
      base.json
  pnpm-workspace.yaml
  package.json
  turbo.json
  CLAUDE.md

pnpm-workspace.yaml इतना ही काफी है।

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

Root package.json में team और Claude Code के लिए repeatable commands रखें। 2 जून 2026 को verified public versions turbo@2.9.16 और pnpm@11.5.1 थे; real project में lockfile reproducibility देता है।

{
  "name": "acme-monorepo",
  "private": true,
  "packageManager": "pnpm@11.5.1",
  "scripts": {
    "dev": "turbo dev",
    "build": "turbo run build",
    "lint": "turbo run lint",
    "test": "turbo run test",
    "type-check": "turbo run type-check",
    "check": "turbo run lint type-check test build",
    "check:affected": "turbo run lint type-check test build --affected"
  },
  "devDependencies": {
    "turbo": "^2.9.16",
    "typescript": "^5.8.3"
  }
}

Internal packages में workspace:* लिखें। इसका मतलब है कि package current workspace से resolve होगा, registry से गलती से नहीं आएगा।

{
  "name": "@acme/ui",
  "version": "0.1.0",
  "private": true,
  "type": "module",
  "main": "./dist/index.js",
  "types": "./dist/index.d.ts",
  "scripts": {
    "build": "tsc -p tsconfig.json",
    "lint": "eslint src --max-warnings=0",
    "type-check": "tsc -p tsconfig.json --noEmit",
    "test": "vitest run"
  },
  "devDependencies": {
    "@acme/tsconfig": "workspace:*",
    "typescript": "^5.8.3",
    "vitest": "^3.1.0",
    "eslint": "^9.25.0"
  }
}

turbo.json में tasks और outputs लिखें

Root turbo.json repository का task contract है। tasks के अंदर हर key package scripts में उसी नाम का command ढूंढती है। ^build का अर्थ है dependency packages का build पहले पूरा हो।

{
  "$schema": "https://turborepo.dev/schema.json",
  "globalDependencies": ["pnpm-lock.yaml", "tsconfig.base.json", ".env.example"],
  "globalEnv": ["NODE_ENV"],
  "tasks": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": ["dist/**", ".next/**", "!.next/cache/**", "out/**"]
    },
    "lint": {
      "dependsOn": ["^build"],
      "outputs": []
    },
    "type-check": {
      "dependsOn": ["^build"],
      "outputs": []
    },
    "test": {
      "dependsOn": ["build"],
      "outputs": ["coverage/**"]
    },
    "dev": {
      "cache": false,
      "persistent": true
    }
  }
}

outputs वे artifacts हैं जिन्हें cache से वापस लाया जा सकता है। अगर यह कम है तो cache मदद नहीं करती। अगर यह बहुत ज्यादा है तो temporary files और framework internals CI artifacts में चले जाते हैं। Next.js में .next/cache/** को exclude करना आम तौर पर safer है।

किसी app की output अलग हो तो package के अंदर turbo.json रखें। Array fields default रूप से inherited value को replace करते हैं; जोड़ना हो तो $TURBO_EXTENDS$ पहले रखें।

{
  "extends": ["//"],
  "tasks": {
    "build": {
      "outputs": ["$TURBO_EXTENDS$", ".next/**", "!.next/cache/**"],
      "env": ["NEXT_PUBLIC_API_URL"]
    }
  }
}

CI को स्थिर बनाएं

Turborepo CI में सबसे ज्यादा फायदा देता है, लेकिन --affected को Git history चाहिए। GitHub Actions में shallow checkout से सभी packages changed लग सकते हैं। इसलिए fetch-depth: 0 रखें।

name: turbo-ci

on:
  pull_request:
  push:
    branches: [main]

permissions:
  contents: read

jobs:
  verify:
    runs-on: ubuntu-latest
    env:
      TURBO_TOKEN: ${{ secrets.TURBO_TOKEN }}
      TURBO_TEAM: ${{ secrets.TURBO_TEAM }}
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: pnpm/action-setup@v4
        with:
          version: 11.5.1
      - uses: actions/setup-node@v4
        with:
          node-version: 22
          cache: pnpm
      - run: pnpm install --frozen-lockfile
      - run: pnpm turbo run lint type-check test build --affected
      - run: pnpm turbo run build --dry=json > turbo-plan.json
      - uses: actions/upload-artifact@v4
        if: always()
        with:
          name: turbo-plan
          path: turbo-plan.json

Remote Cache के लिए local machine पर pnpm dlx turbo login और pnpm dlx turbo link चलाएं। CI में TURBO_TOKEN और TURBO_TEAM secrets से दें। Logs भी artifacts जैसे हो सकते हैं, इसलिए API keys, customer data या session tokens print न करें।

इन commands को CLAUDE.md में रखें।

pnpm turbo run build --dry=json
pnpm turbo run build --filter=@acme/web...
pnpm turbo run test --filter=...[origin/main]
pnpm turbo run lint --filter=!./apps/docs
pnpm turbo run build --cache=local:rw,remote:r
pnpm turbo run build --force

Claude Code के लिए prompt

सिर्फ “Turborepo setup कर दो” न लिखें। Boundaries, forbidden changes और verification commands साफ दें।

This repository is a Turborepo v2 + pnpm workspace monorepo.

Boundaries:
- apps/* are deployable applications.
- packages/ui contains visual components only.
- packages/utils contains framework-independent functions only.
- packages/* must not depend on apps/*.
- turbo.json must use tasks, not pipeline.

Task:
1. Read package.json and turbo.json, then explain the task dependency graph.
2. Point out missing or suspicious outputs for caching.
3. If changes are needed, make the smallest safe diff.
4. Run these commands and report the result:

pnpm turbo run lint type-check test build --affected
pnpm turbo run build --dry=json

यह prompt Claude Code को बड़े और unrelated rewrite से रोकता है। यह packages/ui में HTTP calls, packages/utils में Next.js import, या हर PR पर full build जैसी गलत सलाह भी कम करता है।

आम गलतियां

पहली गलती है पुराने pipeline examples copy करना। Turborepo v2 में tasks इस्तेमाल होता है। Migration में Claude Code से हर changed key को official docs से compare करवाएं।

दूसरी गलती है बहुत ज्यादा cache करना। node_modules/**, temporary logs और non-deployable internal cache को outputs में न डालें। Build artifacts cache करें, पूरा workspace नहीं।

तीसरी गलती है shallow Git history के साथ --affected चलाना। अगर base और head checkout में नहीं हैं, Turborepo सही package set नहीं निकाल सकता।

चौथी गलती है Claude Code को एक साथ बहुत काम देना। पहले Turborepo, फिर root scripts, फिर CI। Package split, ESLint migration और dependency upgrade अलग रखें।

पांचवीं गलती है over-sharing। बड़ा packages/shared हर छोटी change को global बना देता है। ui, utils, contracts, tsconfig जैसे छोटे नाम graph को पढ़ने योग्य रखते हैं।

Revenue flow और अगला कदम

Turborepo केवल speed tool नहीं है। यह revenue paths की रक्षा भी करता है। Content site build टूटने पर publish रोक सकती है। SaaS pricing, signup, settings और admin flow को एक repeatable CI में verify कर सकता है। Team projects में छोटी CI review wait time भी कम करती है।

ClaudeCodeLab teams को CLAUDE.md, package boundaries, CI commands, review prompts और rollout rules बनाने में मदद कर सकता है। Self-study के लिए monorepo management और CI/CD setup पढ़ें। Team adoption के लिए training / consultation से शुरू करें।

असल में आजमाने पर क्या हुआ

Masa ने यह pattern दो Vite apps और एक shared UI package वाले छोटे repository में लगाया। पहली run में सभी tasks चले, बाद की runs में build और type-check पर cache hit दिखा। शुरुआत में outputs बहुत broad था और framework internal cache भी CI artifacts में आ रहा था। Stable version वही रहा जो इस लेख में है: v2 tasks, narrow outputs, affected verification, और Claude Code prompt जो files edit करने से पहले boundaries review करवाता है।