Monorepo

Monorepo, birden fazla uygulama ve paketin tek bir repoda durmasıdır. Ortak UI bileşenlerini, TypeScript ayarlarını ve tipleri ayrı bir repoya bölmeden paylaşırsınız. Takımlar arası koordinasyon maliyeti düşer, paketi ve onu kullanan uygulamaları tek bir değişiklikte güncelleyebilirsiniz.¹ Bu rehber frontend'de en yaygın ikiliyi kuruyor: paketleri birbirine bağlayan pnpm workspace ve görevleri sıralayıp önbelleğe alan Turborepo.

Ne zaman monorepo?

Geçişin zor kısmı çoğu zaman teknik değil, organizasyonel: ekiplerin aynı repoda çalışmayı kabul etmesi gerekiyor.¹

En uç örnek Google: on binlerce geliştirici için tek bir ortak kaynak gerçeği olarak devasa bir tek repo kullanıyor. Communications of the ACM'deki makale, bu modelin avantajlarını ve ödünleşimlerini, onu mümkün kılan sistemler ve iş akışlarıyla birlikte anlatıyor.³ Ödünleşimin frontend'deki karşılığı boyut: kod büyüdükçe build, test ve sürüm kontrolü yavaşlar, editör ağırlaşır.⁴ 2026 tarihli bağımsız bir derleme kabaca şu ölçüyü veriyor: üç veya daha fazla deploy edilebilir uygulama, birkaç paylaşılan paket ve kod tabanında çalışan birden fazla ekip varsa monorepo mantıklı. Tek uygulama ve yaklaşık 10 kişiden küçük ekipler için erken.⁵ Fireship'in deyimiyle monorepo "blogunuz için abartı olabilir".⁴

Takımların bağımsız yayın döngüsü istediği durumlar için Micro Frontend rehberine bakın.

İki araç, iki iş

Turborepo paket yöneticisinin workspace özelliğinin üzerine kuruludur.⁹ Bağımlılıkları indirmek, symlink'lemek ve çözümlemek yine paket yöneticisinin işidir.¹⁰ Aynı işi yapan bir alternatif Nx: mimari sınırları zorlayan mekanizmalar da sunuyor.¹¹ Fireship'in karşılaştırması farkı iyi özetliyor: ikisi de bağımlılık grafiği çıkarır, çıktıları önbelleğe alır ve işleri paralel çalıştırır. Nx daha eski ve geniş (kod üretimi, eklentiler, dağıtık görev çalıştırma), Turborepo daha yeni ve minimal, mevcut workspace'e kolayca eklenir.⁴ (Video 2021 tarihli, araç ayrıntıları değişti, kavramlar geçerli.) 2026 itibarıyla pnpm workspaces yeni monorepo'lar için varsayılan sayılıyor.⁵

Yapı

repo/
├── apps/
│   ├── web/                  # Next.js uygulaması
│   └── admin/                # ikinci uygulama
├── packages/
│   ├── ui/                   # @repo/ui
│   ├── typescript-config/    # @repo/typescript-config
│   └── eslint-config/        # @repo/eslint-config
├── package.json
├── pnpm-workspace.yaml
└── turbo.json

Turborepo dokümanı uygulama ve servisleri apps/ altında, kütüphane ve araçları packages/ altında toplamayı öneriyor.⁹ Anthony Shew'un videosunda da aynı iskelet var: workspace'ler apps ve packages altındaki parçaları tek grafikte bağlıyor, her paketin kendi package.json dosyası, dışa açtığı API için exports alanı ve kendi scripts alanı oluyor.¹²

# pnpm-workspace.yaml
packages:
  - "apps/*"
  - "packages/*"

// package.json (kök)
{
  "private": true,
  "scripts": {
    "build": "turbo run build",
    "dev": "turbo run dev",
    "lint": "turbo run lint"
  },
  "devDependencies": {
    "turbo": "latest"
  }
}

• apps/* ve packages/* altında package.json olan her klasör bir pakettir. İç içe paketler (apps/a ve apps/a/b) desteklenmez.⁹

• Lockfile şart. Turborepo iç paketler arasındaki bağımlılıkları buradan anlıyor.⁹

• Kök dizine yalnızca depo yönetim araçları konur (turbo, husky, lint-staged). Uygulama bağımlılıkları, onları kullanan pakete yazılır.¹⁰ Tally Barak'ın DevOps.js konuşmasındaki uyarıya göre kökte toplanan (hoisted) bağımlılıklar eksik bildirimleri gizleyebilir ve hata ancak deploy'da ortaya çıkar.¹³

Paylaşılan paketler

Bir uygulama, iç paketi npm'deki bir paket gibi ekler. Sürüm yerine paket yöneticisinin workspace sözdizimini yazarsınız:¹⁴

// apps/web/package.json
{
  "dependencies": {
    "@repo/ui": "workspace:*"
  }
}

workspace: protokolünde pnpm yerel workspace paketi dışında hiçbir şeye çözümlemeyi reddeder. Yanlışlıkla registry'den başka bir sürüm inmez.⁶ Paket adında kapsamlı bir önek kullanın. Turborepo dokümanı @repo kullanıyor, çünkü npm'de alınamayan bir ad alanı.⁹

Aynı bağımlılığı birçok paket kullanıyorsa sürümü tek yerde tutmak için pnpm catalogs kullanabilirsiniz (pnpm 9.5 ve sonrası):¹⁰

# pnpm-workspace.yaml
packages:
  - "apps/*"
  - "packages/*"

catalog:
  react: ^19.0.0
  react-dom: ^19.0.0

// apps/web/package.json ve packages/ui/package.json
{
  "dependencies": {
    "react": "catalog:",
    "react-dom": "catalog:"
  }
}

Catalogs üç şey kazandırır: workspace'te her bağımlılığın tek sürümü olur, güncelleme yalnızca pnpm-workspace.yaml'da tek satırlık değişikliktir ve package.json dosyalarında merge çakışması çıkmaz.¹⁵

Paketleri tasarlarken iki kural işinizi görür:

• Her pakete tek amaç: @repo/ui tüm paylaşılan UI bileşenlerini, @repo/typescript-config TypeScript ayarlarını barındırır.¹⁶

• Uygulamalar paylaşılan kod barındırmaz. Ortak kodu ayrı bir pakete koyun, uygulamalar o pakete bağlansın. Uygulamalar paket grafiğinin sonudur.¹⁶

Ortak UI paketi

Bir iç paketi derlemenin iki yolu var:¹⁴

Next.js ve Vite uygulamalarının paylaştığı bir UI paketi için Just-in-Time en az yapılandırmayla başlayan seçenek. Uygulamaların build süresinden memnunsanız önbellek kaybı sorun olmaz.¹⁴

// packages/ui/package.json
{
  "name": "@repo/ui",
  "exports": {
    "./button": "./src/button.tsx",
    "./card": "./src/card.tsx"
  },
  "scripts": {
    "lint": "eslint . --max-warnings 0",
    "check-types": "tsc --noEmit"
  }
}

import { Button } from "@repo/ui/button"

Dosya başına exports tanımlamak, paketi tek bir barrel dosyasına bağlamaktan kaçınmanızı sağlar. Barrel dosyaları derleyiciler ve bundler'lar için zordur.⁹ Önceki rehberdeki index.ts tartışmasının paket düzeyindeki karşılığı bu.

TypeScript ayarını da paylaşın. packages/typescript-config altında base.json ve nextjs.json, react-library.json gibi varyantlar durur, her paket kendi tsconfig.json'ında extends ile bunlardan birini seçer:¹⁷

// apps/web/tsconfig.json
{
  "extends": "@repo/typescript-config/nextjs.json",
  "include": ["src"],
  "exclude": ["node_modules"]
}

Kök dizinde tsconfig.json'a genellikle ihtiyacınız yok. Kökteki bir değişiklik tüm görevlerin önbelleğini düşürür.¹⁷

shadcn/ui kullanıyorsanız CLI monorepo'yu tanıyor. pnpm dlx shadcn@latest init --monorepo iki workspace (web ve ui) ve Turborepo kurar. apps/web içinde add button çalıştırdığınızda bileşen packages/ui altına iner ve import yolları güncellenir. Bileşenler @workspace/ui/components/button gibi import edilir.¹⁸ Her workspace'te bir components.json bulunmalı, style, iconLibrary ve baseColor ikisinde de aynı olmalı. Tailwind CSS v4'te components.json içindeki tailwind.config alanı boş bırakılır.¹⁸ shadcn paketi @workspace/ui adıyla kuruyor, bu rehberdeki @repo/ui ile aynı rolde: shadcn kullanıyorsanız onun adını koruyun.

turbo.json: görevler ve önbellek

// turbo.json
{
  "tasks": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": [".next/**", "!.next/cache/**", "!.next/dev/**", "dist/**"]
    },
    "lint": {
      "dependsOn": ["^lint"]
    },
    "check-types": {
      "dependsOn": ["^check-types"]
    },
    "dev": {
      "cache": false,
      "persistent": true
    }
  }
}

Her tasks anahtarı, paketlerin package.json dosyasındaki aynı adlı script'i çalıştırır.⁷

• ^build: Bir paketten önce bağımlılıklarının build görevini çalıştırır. @repo/ui derlenip bittikten sonra web derlenir.⁷

• outputs: Hangi dosyaların önbelleğe alınacağını söyler. Yazmazsanız Turborepo dosyaları önbelleğe almaz ve önbellekten dönen çalıştırma dosyaları geri getirmez.⁷⁸

• dev: Hiç bitmeyen bir görev olduğu için persistent: true ve cache: false alır.⁷

Önbellek girdilerin parmak izine dayanır. Aynı parmak izi yeniden gelirse Turborepo işi yeniden yapmaz, sonucu önbellekten geri getirir.⁸ Yerel önbellek .turbo/cache klasöründe durur. npx turbo login ve npx turbo link ile Remote Cache'i açarsanız takım arkadaşlarınız ve CI aynı önbelleği paylaşır.⁸ Kök package.json'daki bir bağımlılığı güncellemek tüm görevlerin önbelleğini düşürür, kök dizini ince tutmanın pratik gerekçesi bu.⁸

check-types için ^check-types doğru önbellek davranışı verir ama görevleri paralel çalıştırmaz. Hem doğruluk hem paralellik için Turborepo dokümanı Transit Node kalıbını öneriyor.⁷

Görevleri çalıştırma

turbo run build                 # tüm paketler
turbo run build --filter=web... # web ve bağımlılıkları
turbo run build --filter=...ui  # ui ve onu kullanan paketler
turbo run build test lint       # birden çok görev, mümkün olduğunca paralel

... sonda bağımlılıkları, başta bağımlıları (dependents) kapsar.¹⁹ Bir paketi değiştirirken --filter=...ui ile onu kullanan her şeyin hâlâ derlendiğini görebilirsiniz.¹⁹

CI ve Docker

Önbelleğin asıl değeri CI'da ortaya çıkıyor. Michael Guay'in videosunda pnpm ve Turborepo ile bir Next.js ön yüzü ile NestJS arka yüzü tek workspace'te kuruluyor. TypeScript ve ESLint ayarları ile DTO tipleri paylaşılan paketlerde duruyor. GitHub Actions hattında Vercel Remote Cache bağlanınca daha önce derlenmiş çıktılar yeniden derlenmeden önbellekten geliyor.²⁰ Shew'nun videosunda da aynı etki var: Remote Cache ile CI/CD'deki dağıtım süreçleri saniyelere iniyor.¹² Turborepo'nun Docker rehberine göre kimlik bilgileri (TURBO_TEAM, TURBO_TOKEN) build argümanı olarak verilir. Yalnızca derleme aşamasında kullanıldıkları için son imaja girmezler.²¹

Monorepo'da bir uygulamayı Docker'a koyarken sorun şu: bir uygulamanın kilit dosyasındaki ilgisiz bir değişiklik, başka bir uygulamanın Docker build'ini gereksiz yere geçersiz kılabilir.²¹ turbo prune, hedef uygulamanın ihtiyaç duyduğu workspace'leri ve budanmış bir kilit dosyasını içeren küçük bir kopya üretir:²¹

turbo prune web --docker

--docker bayrağı çıktıyı ikiye böler: out/json yalnızca package.json dosyalarını (az değişir, bağımlılık kurulumu için), out/full ise kaynak kodu içerir. Budanmış kilit dosyası out/ kökünde durur.²² Çok aşamalı bir Dockerfile'da önce json ve kilit dosyasıyla bağımlılıkları kurar, sonra full ile derlersiniz. Böylece bağımlılıklar değişmedikçe kurulum katmanı önbellekte kalır.²¹ Tam Dockerfile için Turborepo'nun Docker rehberine bakın.

Kendin dene

1. pnpm dlx create-turbo@latest ile örnek bir repo oluşturun. apps/web ile packages/ui arasındaki workspace:* bağını inceleyin.

2. turbo run build komutunu iki kez çalıştırın. İkincisinde önbellekten dönen sonucu görün.

3. packages/ui içinde bir bileşeni değiştirin ve turbo run build --filter=...ui çalıştırın. Hangi paketlerin yeniden derlendiğine bakın.

4. turbo.json'dan outputs'u silip tekrar deneyin. Önbellekten dönen build'in dosyaları geri getirmediğini görün.

5. Fireship'in Monorepos: Turborepo vs Nx videosunu (9 dk) izleyin. Ardından Tally Barak'ın 1001 Packages konuşmasından (24 dk) sürümleme ve bağımlılık kurulumu bölümlerine bakın.¹³ Daha sohbet havasında bir giriş için Syntax'ın monorepo bölümü de iyi: workspace'ler, pnpm, Turborepo, Nx, Lerna ve Rush üzerine.²³

6. Sıfırdan başlamak için Anthony Shew'nun How to structure a JS/TS monorepo videosu, yalnızca pnpm tarafını görmek için de Code with tkssharma'nın PNPM Workspaces Deep Dive videosu var. İkincisinde pnpm-workspace.yaml ile api ve utils paketi kurulup workspace: ile bağlanıyor.²⁴

7. Bir uygulamanız varsa turbo prune <uygulama> --docker çalıştırın ve out/json ile out/full klasörlerine bakın.²²