Claude Code dan Turborepo: panduan monorepo praktis

Mengapa Claude Code cocok dengan Turborepo

Monorepo menyimpan beberapa aplikasi dan package bersama di satu repository. Awalnya apps/web dan packages/ui terlihat cukup. Setelah ada aplikasi admin, dokumentasi, utilitas bersama, beberapa target deploy, dan CI yang semakin lama, masalah sebenarnya muncul: urutan build, batas dependency, waktu CI, dan strategi cache.

Turborepo merapikan pekerjaan itu dengan task graph dan cache. Claude Code berguna ketika dipakai sebagai reviewer repository, bukan sekadar pembuat config. Ia bisa membaca package.json, menjelaskan dependency antar-package, menemukan outputs yang kurang, dan menyarankan perintah CI yang hanya menyentuh bagian yang berubah.

Panduan ini memakai Turborepo v2 per 2 Juni 2026. Di turbo.json, gunakan tasks, bukan pipeline lama. Saat mengadaptasi contoh, cek sumber resmi: Turborepo configuration, turbo run, Remote Caching, dan Claude Code memory.

Untuk konteks ClaudeCodeLab, lanjutkan dengan manajemen monorepo, pnpm workspace dengan Claude Code, dan Claude Code CI/CD setup.

Bentuk target dan tiga use case

Targetnya adalah monorepo TypeScript kecil di atas pnpm workspace. Mulai dari struktur kecil karena Claude Code lebih mudah mengikuti batas yang eksplisit daripada package samar bernama shared atau common.

flowchart LR
  web["apps/web\nAplikasi pelanggan"] --> ui["packages/ui\nUI bersama"]
  admin["apps/admin\nAplikasi admin"] --> ui
  web --> utils["packages/utils\nFungsi bersama"]
  admin --> utils
  ui --> tsconfig["packages/tsconfig\nKonfig TS"]
  utils --> tsconfig

Use case pertama adalah produk dengan aplikasi pelanggan dan aplikasi admin yang memakai tombol, form, dan validator yang sama. Memisahkan packages/ui dari packages/utils membuat Claude Code tidak mudah mencampur komponen visual dengan fungsi bisnis.

Use case kedua adalah platform konten atau dokumentasi. Landing page, docs, dan dashboard internal sering berada di repository yang sama. Menjalankan semua task pada setiap PR akan lambat. --affected dan --filter membantu memverifikasi hanya package yang berubah dan package yang terdampak.

Use case ketiga adalah SaaS yang punya jalur revenue. Pricing, signup, account settings, dan admin sering berbagi package kecil. Jika lint, type-check, test, dan build stabil, Claude Code bisa mengubah CTA atau onboarding tanpa melewati pengaman CI.

Salin struktur minimum

Tetapkan bentuk repository dulu. Jumlah package bukan yang utama; yang penting setiap package punya tanggung jawab yang jelas.

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 cukup sederhana.

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

Di root package.json, simpan command Turborepo yang akan dipakai tim dan Claude Code. Pada 2 Juni 2026, versi publik yang saya cek adalah turbo@2.9.16 dan pnpm@11.5.1; di proyek nyata, lockfile yang membuat hasilnya reproducible.

{
  "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"
  }
}

Package internal memakai workspace:*. Ini memberi tahu package manager agar mengambil package dari workspace ini, bukan package dengan nama sama dari 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"
  }
}

Definisikan turbo.json dengan tasks dan outputs

Root turbo.json adalah kontrak task repository. Setiap key dalam tasks mencari script bernama sama di package. ^build berarti dependency package harus menjalankan build lebih dulu.

{
  "$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 adalah artifact yang boleh dipulihkan dari cache. Jika terlalu sedikit, cache tidak membantu. Jika terlalu luas, file sementara dan cache internal framework ikut masuk ke artifact CI. Untuk Next.js, mengecualikan .next/cache/** biasanya lebih aman.

Jika satu aplikasi punya artifact khusus, tambahkan turbo.json di dalam package. Field array mengganti nilai turunan secara default; pakai $TURBO_EXTENDS$ di awal untuk menambahkan.

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

Buat CI yang mudah diprediksi

Turborepo paling terasa di CI, tetapi --affected butuh riwayat Git. Di GitHub Actions, checkout yang terlalu dangkal bisa membuat semua package terlihat berubah. Gunakan 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

Untuk Remote Cache, hubungkan repository secara lokal dengan pnpm dlx turbo login dan pnpm dlx turbo link, lalu berikan TURBO_TOKEN dan TURBO_TEAM lewat secret CI. Log juga bisa dianggap artifact, jadi jangan mencetak API key, data pelanggan, atau session token dari build script.

Simpan command harian di 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

Prompt untuk Claude Code

Jangan hanya meminta “setup Turborepo”. Berikan batas, larangan, dan command verifikasi.

Repository ini adalah monorepo Turborepo v2 + pnpm workspace.

Batas:
- apps/* adalah aplikasi yang bisa dideploy.
- packages/ui hanya berisi komponen visual.
- packages/utils hanya berisi fungsi yang tidak bergantung framework.
- packages/* tidak boleh bergantung pada apps/*.
- turbo.json harus memakai tasks, bukan pipeline.

Tugas:
1. Baca package.json dan turbo.json, lalu jelaskan task dependency graph.
2. Tunjukkan outputs cache yang kurang atau mencurigakan.
3. Jika perlu perubahan, buat diff aman sekecil mungkin.
4. Jalankan command ini dan laporkan hasilnya:

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

Prompt ini mengurangi kegagalan umum AI: rewrite besar yang tidak terkait. Ini juga membantu menolak saran buruk seperti HTTP call di packages/ui, import Next.js dari packages/utils, atau CI yang hanya menjalankan full build.

Kesalahan umum

Kesalahan pertama adalah menyalin contoh lama dengan pipeline. Turborepo v2 memakai tasks. Saat migrasi, minta Claude Code menjelaskan setiap key yang berubah dengan mengacu pada dokumentasi resmi.

Kesalahan kedua adalah cache terlalu luas. Jangan masukkan node_modules/**, log sementara, atau cache internal yang tidak dideploy ke outputs. Cache artifact build, bukan seluruh workspace.

Kesalahan ketiga adalah memakai --affected tanpa riwayat Git yang cukup. Jika base dan head tidak ada di checkout, Turborepo tidak bisa menghitung package yang benar.

Kesalahan keempat adalah memberi Claude Code terlalu banyak pekerjaan sekaligus. Masukkan Turborepo dulu, lalu root scripts, lalu CI. Package split, migrasi ESLint, dan upgrade dependency sebaiknya menjadi langkah terpisah.

Kesalahan kelima adalah terlalu banyak berbagi. packages/shared yang besar membuat perubahan kecil terasa global. Package bernama ui, utils, contracts, dan tsconfig lebih mudah dibaca.

Monetisasi dan langkah berikutnya

Turborepo bukan hanya alat mempercepat build. Ia melindungi jalur revenue. Situs konten bisa menghentikan publikasi saat build gagal. SaaS bisa memverifikasi pricing, signup, settings, dan admin dalam satu alur. Untuk tim konsultasi, CI yang lebih pendek berarti antrean review lebih pendek.

ClaudeCodeLab dapat membantu tim menjadikan ini praktik kerja: CLAUDE.md, batas package, command CI, prompt review, dan aturan rollout. Untuk belajar sendiri, lanjutkan ke manajemen monorepo dan CI/CD dengan Claude Code. Untuk adopsi tim, mulai dari training / consultation.

Hasil saat dicoba

Masa menerapkan pola ini pada repository kecil dengan dua aplikasi Vite dan satu package UI bersama. Run pertama menjalankan semua task; run berikutnya menunjukkan cache hit pada build dan type-check. Masalah awalnya adalah outputs terlalu luas sehingga cache internal framework ikut masuk artifact CI. Versi yang stabil adalah yang ditulis di sini: tasks v2, outputs sempit, verifikasi affected, dan prompt Claude Code yang meninjau batas sebelum mengubah file.