Mikirin monorepo itu kayak mikirin kamar kos yang isinya banyak banget barang. Tanpa sistem yang rapi, kamu bakal habis waktu nyari "di mana sih komponen Button itu?" atau nunggu build berjam-jam karena satu package dikompilasi berulang kali tiap ada perubahan kecil. Turborepo hadir untuk ngehandle masalah ini. Ini adalah build system berkecepatan tinggi yang dirancang khusus untuk monorepo JavaScript/TypeScript. Dibuat oleh tim yang sama di balik Vercel, Turborepo fokus pada satu hal: bikin task di monorepo jalan seefisien mungkin dengan caching dan parallel execution. Artikel ini bakal bahas cara setup Turborepo dari nol pake pnpm sebagai package manager, konfigurasi `turbo.json`, remote caching, task filtering, dan strategi optimasi build. ## Apa Itu Turborepo? Sebelum bahas cara pakenya, pahami dulu masalah apa yang Turborepo selesaikan. Di monorepo tanpa build system yang baik, kamu hadapi beberapa masalah: 1. **Build berurutan yang lambat**: kalo package A depend pada package B dan C, dan kamu build semuanya satu per satu, total waktu build = A + B + C. Padahal B dan C bisa di-build bareng-bareng (paralel). 2. **Build ulang yang gak perlu**: kamu ubah kode di package B, terus build semua. Package C yang gak ada hubungannya dengan B ikut di-build ulang. Buang waktu. 3. **Task management manual**: kamu harus inget urutan task mana yang harus jalan duluan. `lint`, `test`, `build` - mana duluan? Gimana kalo ada package yang gagal test? Turborepo selesain ketiganya dengan: - **DAG (Directed Acyclic Graph)**: otomatis detect dependency antar package dan jalanin task sesuai urutan yang benar. - **Content-aware caching**: kalo input (kode, config, dependency) gak berubah, output diambil dari cache. Selesai dalam hitungan milidetik. - **Parallel execution**: task yang gak saling depend jalan barengan, pakai semua core CPU yang tersedia. ## Setup Monorepo dengan pnpm ### Step 1: Install Tools Kamu butuh pnpm (package manager yang efisien untuk monorepo) dan Turborepo: ```bash # Install pnpm npm install -g pnpm # Install turbo globally (opsional, bisa juga pake npx) pnpm add -g turbo ``` ### Step 2: Bikin Struktur Project Struktur monorepo standar dengan Turborepo: ``` my-monorepo/ ├── apps/ │ ├── web/ # Next.js app │ │ ├── package.json │ │ ├── tsconfig.json │ │ └── ... │ ├── admin/ # Admin dashboard │ │ ├── package.json │ │ └── ... │ └── api/ # Backend API │ ├── package.json │ └── ... ├── packages/ │ ├── ui/ # Shared UI components │ │ ├── package.json │ │ └── ... │ ├── utils/ # Shared utilities │ │ ├── package.json │ │ └── ... │ ├── config/ # Shared config (eslint, tsconfig, dll) │ │ ├── package.json │ │ └── ... │ └── types/ # Shared TypeScript types │ ├── package.json │ └── ... ├── package.json ├── turbo.json ├── pnpm-workspace.yaml └── tsconfig.json ``` ### Step 3: Setup pnpm Workspace Bikin file `pnpm-workspace.yaml` di root: ```yaml packages: - "apps/*" - "packages/*" ``` Ini bilang ke pnpm bahwa folder `apps/*` dan `packages/*` adalah workspace packages. ### Step 4: Root package.json ```json { "name": "my-monorepo", "private": true, "scripts": { "build": "turbo run build", "dev": "turbo run dev", "lint": "turbo run lint", "test": "turbo run test", "clean": "turbo run clean && rm -rf node_modules" }, "devDependencies": { "turbo": "^2.0.0" }, "packageManager": "pnpm@9.0.0", "engines": { "node": ">=20" } } ``` ### Step 5: Install Dependencies ```bash pnpm install ``` pnpm otomatis detect workspace dan hubungkan internal packages. Kalo package `web` depend pada `@my-monorepo/ui`, pnpm bakal symlink mereka secara otomatis. ### Step 6: Tambahkan Dependency Antar Package Contoh: app `web` butuh package `ui` dan `utils`: ```json // apps/web/package.json { "name": "@my-monorepo/web", "dependencies": { "@my-monorepo/ui": "workspace:*", "@my-monorepo/utils": "workspace:*", "next": "^14.0.0", "react": "^18.0.0" } } ``` `workspace:*` artinya pnpm akan resolve package dari monorepo, bukan dari npm registry. ## Konfigurasi turbo.json File `turbo.json` adalah jantung dari Turborepo. Di sini kamu definisin task apa yang ada, dependency antar task, dan strategi caching. Konfigurasi dasar: ```json { "$schema": "https://turbo.build/schema.json", "tasks": { "build": { "dependsOn": ["^build"], "outputs": ["dist/**", ".next/**", "!.next/cache/**"] }, "dev": { "cache": false, "persistent": true }, "lint": { "dependsOn": ["^build"] }, "test": { "dependsOn": ["^build"], "outputs": ["coverage/**"] }, "clean": { "cache": false } } } ``` Mari bahas setiap bagian: ### `dependsOn` - Task Dependencies `"dependsOn": ["^build"]` artinya: sebelum jalanin `build` di package ini, jalanin `build` di semua package dependency (yang ditandai dengan `^` prefix). Kalo `web` depend pada `ui`, maka `build` di `ui` akan jalan duluan, baru `build` di `web`. Kamu juga bisa specify dependency lebih granular: ```json { "tasks": { "build": { "dependsOn": ["^build"] }, "test": { "dependsOn": ["build"] }, "deploy": { "dependsOn": ["build", "test", "^lint"] } } } ``` - `"dependsOn": ["^build"]` - build semua dependency dulu, baru build package ini - `"dependsOn": ["build"]` - build package ini dulu (di package yang sama), baru jalanin task - `"dependsOn": ["test"]` - task `test` harus selesai di package yang sama dulu ### `outputs` - Apa yang Di-cache `outputs` mendefinisikan folder mana yang hasilnya harus disimpen di cache. Kalo gak ditentukan, turbo gak bakal cache output: ```json { "build": { "outputs": ["dist/**", ".next/**", "!.next/cache/**"] } } ``` - `dist/**` - cache semua isi folder `dist` - `.next/**` - cache build output Next.js - `!.next/cache/**` - kecuali folder cache internal Next.js (gak perlu) Pola yang support: - `**` - recursive wildcard - `*` - single level wildcard - `!` - negasi (exclude) ### `inputs` - Apa yang Memicu Cache Miss Secara default, Turbo cache berdasarkan hash dari semua file di package. Tapi kamu bisa specify `inputs` untuk kontrol lebih presisi: ```json { "tasks": { "test": { "dependsOn": ["^build"], "inputs": [ "src/**", "test/**", "package.json", "tsconfig.json", "vitest.config.ts" ], "outputs": ["coverage/**"] } } } ``` Dengan `inputs` ini, test cuma bakal re-run kalo file di `src/`, `test/`, atau config yang disebutin berubah. Kalo kamu cuma ubah README, test gak bakal jalan ulang. ### `persistent` - Long-running Tasks Untuk task yang gak selesai (kayak dev server), set `persistent: true`: ```json { "dev": { "cache": false, "persistent": true } } ``` Turbo gak bakal nyoba cache atau nunggu task ini selesai. ### `env` - Environment Variables untuk Cache Key Kalo output build dipengaruhi oleh environment variable, kamu harus daftarin mereka supaya cache key-nya bener: ```json { "tasks": { "build": { "dependsOn": ["^build"], "outputs": ["dist/**", ".next/**"], "env": [ "NODE_ENV", "NEXT_PUBLIC_API_URL", "DATABASE_URL" ] } } } ``` Atau pake wildcard prefix untuk catch semua var yang punya prefix tertentu: ```json { "env": [ "NEXT_PUBLIC_*" ] } ``` ## Menjalankan Task dengan Turbo ### Build Semua ```bash turbo run build ``` Turbo otomatis: 1. Baca dependency graph dari semua package 2. Tentuin urutan build berdasarkan dependency 3. Build package yang gak depend satu sama lain secara paralel 4. Cache hasil build ### Dev Mode ```bash turbo run dev ``` Ini bakal nyalain dev server untuk semua package yang punya task `dev`. Semua jalan barengan, dan log dari masing-masing ditampilkan dengan prefix nama package. ### Task Spesifik ```bash turbo run lint turbo run test turbo run clean ``` ## Task Filtering - Jalankan Task pada Package Tertentu Filtering adalah salah satu fitur paling powerful di Turborepo. Kamu bisa jalankan task hanya pada package tertentu tanpa harus tau path-nya. ### Filter by Package Name ```bash # Build hanya package web turbo run build --filter=web # Build package web dan semua dependency-nya turbo run build --filter=web... # Build package web dan semua package yang depend pada web turbo run build --filter=...web # Kombinasi: web, dependency-nya, dan yang depend pada web turbo run build --filter=...web... ``` ### Filter by Directory ```bash # Build semua package di folder apps/ turbo run build --filter=./apps/* # Build package di direktori tertentu dan dependency-nya turbo run build --filter=./apps/web... ``` ### Filter by Git Changes Ini salah satu fitur paling berguna untuk CI: ```bash # Build package yang berubah sejak commit terakhir turbo run build --filter=...[HEAD^] # Build package yang berubah dari branch main turbo run build --filter=...[origin/main] # Test hanya package yang berubah + yang depend pada mereka turbo run test --filter=...[origin/main] ``` ### Filter by Multiple Criteria ```bash # Build web dan admin turbo run build --filter=web --filter=admin # Build semua kecuali api turbo run build --filter="!api" # Kombinasi complex turbo run build --filter="...[origin/main]" --filter="!@my-monorepo/types" ``` ### Filter dengan Tags Kamu bisa tag package untuk grouping: ```json // packages/ui/package.json { "name": "@my-monorepo/ui", "turbo": { "tags": ["frontend", "shared"] } } ``` ```bash # Build semua package dengan tag frontend turbo run build --filter=frontend ``` ## Remote Caching Local caching (yang udah aktif by default) cuma berguna untuk satu mesin. Remote caching bikin cache shareable antar mesin - developer lain, CI server, semuanya bisa pake cache yang sama. Artinya: kalo developer A udah build package tertentu, dan developer B pull branch yang sama, mereka gak perlu build ulang. Cukup ambil dari remote cache. Selesai dalam hitungan detik. ### Setup Remote Cache dengan Vercel Cara termudah adalah pake Vercel sebagai remote cache provider: ```bash # Login ke Vercel npx turbo login # Link monorepo ke Vercel team npx turbo link ``` Setelah ini, semua cache otomatis sync ke Vercel. Gak perlu konfigurasi tambahan. ### Verifikasi Remote Cache ```bash # Hapus local cache dulu rm -rf .turbo node_modules/.cache # Build - harus ambil dari remote cache turbo run build --remote-only ``` Kalo remote cache working, kamu bakal lihat `FULL TURBO` di output, yang artinya cache hit. ### Custom Remote Cache Server Kalo kamu gak mau pake Vercel, kamu bisa host sendiri remote cache server. Turborepo pake protokol yang kompatibel dengan custom server: ```bash # Set custom cache server URL export TURBO_API="https://my-cache-server.com" # Set auth token export TURBO_TOKEN="my-secret-token" # Set team ID export TURBO_TEAM="my-team" ``` Server kamu harus support endpoint: - `GET /v8/artifacts/:hash` - ambil artifact - `PUT /v8/artifacts/:hash` - simpan artifact - `HEAD /v8/artifacts/:hash` - cek apakah artifact exists Beberapa opsi open-source untuk self-hosted cache server: - `turbo-remote-cache-server` (Docker) - Cloudflare Worker + R2 - Supabase + Edge Function ### Environment Variables untuk Cache Pastikan kamu pake environment variable yang konsisten antar mesin: ```bash # CI - ambil dari GitHub Secrets export TURBO_REMOTE_CACHE_READ_ONLY="false" export TURBO_TOKEN="${{ secrets.TURBO_TOKEN }}" export TURBO_TEAM="${{ secrets.TURBO_TEAM }}" ``` ## Contoh Nyata: Monorepo Lengkap Mari lihat setup lengkap untuk monorepo dengan Next.js, shared UI library, dan shared utils. ### Struktur Final ``` my-monorepo/ ├── apps/ │ ├── web/ │ │ ├── src/ │ │ │ ├── app/ │ │ │ │ ├── page.tsx │ │ │ │ └── layout.tsx │ │ │ └── components/ │ │ ├── package.json │ │ ├── tsconfig.json │ │ └── next.config.js │ └── docs/ │ ├── src/ │ ├── package.json │ └── tsconfig.json ├── packages/ │ ├── ui/ │ │ ├── src/ │ │ │ ├── button.tsx │ │ │ ├── card.tsx │ │ │ └── index.ts │ │ ├── package.json │ │ └── tsconfig.json │ ├── utils/ │ │ ├── src/ │ │ │ ├── format.ts │ │ │ └── index.ts │ │ ├── package.json │ │ └── tsconfig.json │ ├── tsconfig/ │ │ ├── base.json │ │ ├── nextjs.json │ │ ├── react-library.json │ │ └── package.json │ └── eslint-config/ │ ├── index.js │ └── package.json ├── package.json ├── turbo.json ├── pnpm-workspace.yaml └── tsconfig.json ``` ### Package: ui ```json // packages/ui/package.json { "name": "@my-monorepo/ui", "version": "0.0.0", "private": true, "main": "./src/index.ts", "types": "./src/index.ts", "scripts": { "build": "tsc --project tsconfig.json", "lint": "eslint .", "clean": "rm -rf dist .turbo" }, "dependencies": { "react": "^18.0.0" }, "devDependencies": { "@my-monorepo/tsconfig": "workspace:*", "typescript": "^5.0.0" } } ``` ```typescript // packages/ui/src/button.tsx import { type ButtonHTMLAttributes, forwardRef } from 'react'; interface ButtonProps extends ButtonHTMLAttributes { variant?: 'primary' | 'secondary' | 'danger'; size?: 'sm' | 'md' | 'lg'; } export const Button = forwardRef( ({ variant = 'primary', size = 'md', className = '', ...props }, ref) => { const baseStyle = 'inline-flex items-center justify-center rounded-md font-medium transition-colors'; const variants = { primary: 'bg-blue-500 text-white hover:bg-blue-600', secondary: 'bg-gray-200 text-gray-900 hover:bg-gray-300', danger: 'bg-red-500 text-white hover:bg-red-600', }; const sizes = { sm: 'px-3 py-1.5 text-sm', md: 'px-4 py-2 text-base', lg: 'px-6 py-3 text-lg', }; return ( ); } ``` ### Shared TSConfig ```json // packages/tsconfig/base.json { "$schema": "https://json.schemastore.org/tsconfig", "compilerOptions": { "strict": true, "esModuleInterop": true, "skipLibCheck": true, "forceConsistentCasingInFileNames": true, "moduleResolution": "bundler", "module": "esnext", "target": "es2022", "lib": ["es2022", "dom", "dom.iterable"] } } ``` ```json // packages/tsconfig/nextjs.json { "$schema": "https://json.schemastore.org/tsconfig", "extends": "./base.json", "compilerOptions": { "plugins": [{ "name": "next" }], "allowJs": true, "jsx": "preserve", "noEmit": true, "incremental": true } } ``` ```json // packages/tsconfig/react-library.json { "$schema": "https://json.schemastore.org/tsconfig", "extends": "./base.json", "compilerOptions": { "jsx": "react-jsx", "declaration": true, "declarationMap": true, "sourceMap": true, "outDir": "dist" } } ``` ### turbo.json Final ```json { "$schema": "https://turbo.build/schema.json", "globalDependencies": ["**/.env.*local"], "globalEnv": ["NODE_ENV"], "tasks": { "build": { "dependsOn": ["^build"], "outputs": ["dist/**", ".next/**", "!.next/cache/**"], "env": [ "NEXT_PUBLIC_API_URL", "DATABASE_URL" ] }, "dev": { "cache": false, "persistent": true }, "lint": { "dependsOn": ["^build"] }, "test": { "dependsOn": ["^build"], "inputs": [ "src/**/*.tsx", "src/**/*.ts", "test/**/*.ts", "test/**/*.tsx", "package.json", "tsconfig.json", "vitest.config.ts" ], "outputs": ["coverage/**"] }, "clean": { "cache": false }, "type-check": { "dependsOn": ["^build"], "outputs": [] } } } ``` ## CI/CD Integration ### GitHub Actions ```yaml name: CI on: push: branches: [main] pull_request: branches: [main] jobs: build: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 with: fetch-depth: 2 - uses: pnpm/action-setup@v2 with: version: 9 - uses: actions/setup-node@v4 with: node-version: 20 cache: 'pnpm' - run: pnpm install --frozen-lockfile - name: Build changed packages only env: TURBO_TOKEN: ${{ secrets.TURBO_TOKEN }} TURBO_TEAM: ${{ secrets.TURBO_TEAM }} run: pnpm turbo run build lint test --filter=...[origin/main] ``` Kuncinya di `--filter=...[origin/main]` - hanya package yang berubah (dan yang depend pada mereka) yang di-build, lint, dan test. Ini bisa hemat puluhan menit di CI untuk monorepo besar. ### Parallel Jobs Untuk monorepo yang lebih besar, kamu bisa pecah jadi beberapa parallel job: ```yaml jobs: lint: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: pnpm/action-setup@v2 with: version: 9 - run: pnpm install --frozen-lockfile - run: pnpm turbo run lint --filter=...[origin/main] env: TURBO_TOKEN: ${{ secrets.TURBO_TOKEN }} TURBO_TEAM: ${{ secrets.TURBO_TEAM }} test: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: pnpm/action-setup@v2 with: version: 9 - run: pnpm install --frozen-lockfile - run: pnpm turbo run test --filter=...[origin/main] env: TURBO_TOKEN: ${{ secrets.TURBO_TOKEN }} TURBO_TEAM: ${{ secrets.TURBO_TEAM }} build: runs-on: ubuntu-latest needs: [lint, test] steps: - uses: actions/checkout@v4 - uses: pnpm/action-setup@v2 with: version: 9 - run: pnpm install --frozen-lockfile - run: pnpm turbo run build --filter=...[origin/main] env: TURBO_TOKEN: ${{ secrets.TURBO_TOKEN }} TURBO_TEAM: ${{ secrets.TURBO_TEAM }} ``` ## Optimasi Build Beberapa strategi untuk bikin build makin cepat: ### 1. Pake `inputs` dengan Presisi Kalo kamu gak specify `inputs`, Turbo hash semua file di package. Tapi kalo kamu specify dengan presisi, kamu kurangi false cache miss: ```json { "test": { "inputs": [ "src/**", "test/**", "package.json", "tsconfig.json" ] } } ``` Sekarang ubah README gak bakal trigger test ulang. ### 2. Global Dependencies dengan Bijak `globalDependencies` bikin task re-run kalo file global berubah. Pake cuma untuk file yang beneran mempengaruhi semua package: ```json { "globalDependencies": [ "tsconfig.json", "biome.json", ".env" ] } ``` ### 3. `globalPassThroughEnv` Beberapa env var gak boleh masuk cache key. Gunakan `globalPassThroughEnv` untuk bypass: ```json { "globalPassThroughEnv": [ "CI", "GITHUB_TOKEN", "VERCEL_URL" ] } ``` ### 4. Dry Run untuk Analisis Pake `--dry` untuk lihat task graph tanpa jalanin: ```bash turbo run build --dry ``` Output-nya nunjukin task mana yang bakal jalan, urutannya, dan apakah cache hit atau miss. Bagus untuk debug kenapa sesuatu build ulang terus. ```bash turbo run build --dry=json ``` Versi JSON lebih detail, berguna untuk scripting atau CI analysis. ### 5. Profile Build Performance ```bash turbo run build --profile=build-profile.json ``` File ini bisa kamu buka di Chrome DevTools (tab Performance > Load profile) untuk lihat timeline build secara visual. Kamu bisa lihat mana task yang paling lama dan mana yang jalan paralel. ## Tips dan Best Practices 1. **Version packages dengan `workspace:*`** - gak perlu update version manual tiap kali publish. pnpm otomatis resolve ke versi lokal. 2. **Shared config packages** - taruh tsconfig, eslint config, biome config, dan config lain di `packages/` sebagai package sendiri. Bikin semua package extend dari sana, jadi config konsisten di mana-mana. 3. **Pake `pnpm --filter` untuk install** - install dependency ke package tertentu tanpa harus cd ke sana: ```bash pnpm --filter @my-monorepo/web add axios pnpm --filter @my-monorepo/ui add clsx ``` 4. **Lock file discipline** - selalu commit `pnpm-lock.yaml`. Gak pernah edit manual. Selalu pake `pnpm install` untuk update. 5. **Naming convention** - pake consistent naming untuk packages, contoh: `@/`. Ini bikin filter lebih gampang dan menghindari konflik dengan package public. 6. **Jangan terlalu banyak package** - setiap package nambah overhead. Kalo dua package selalu berubah barengan, mungkin gabungin aja jadi satu. ## Perbandingan dengan Alternatif | Fitur | Turborepo | Nx | Lerna | |-------|-----------|-----|-------| | Bahasa | Rust (turbo CLI) + Go (server) | TypeScript | JavaScript | | Kecepatan | Sangat cepat | Cepat | Sedang | | Remote caching | Built-in (Vercel) atau self-hosted | Plugin (Nx Cloud) | Manual | | Task orchestration | DAG-based | DAG-based + plugins | Basic | | Code generation | Terbatas | Powerful (schematics) | Terbatas | | Learning curve | Rendah | Menengah-Tinggi | Rendah | | Editor integration | Basic | Powerful (VS Code extension) | Basic | | Open source | Ya | Ya | Ya | Turborepo unggul di: simplicity, kecepatan, dan DX (developer experience). Pilihan tepat kalo kamu mau monorepo yang cepat tanpa banyak setup. Nx unggul di: code generation, dependency graph visualization, dan plugin ecosystem. Lebih cocok untuk monorepo enterprise yang super besar. ## Penutup Turborepo bikin monorepo jadi menyenangkan. Yang biasanya jadi sumber pusing - dependency management, build order, caching - semua di-handle otomatis. Dengan pnpm sebagai package manager dan remote caching yang aktif, kamu dapet setup monorepo yang cepat, efisien, dan gampang di-maintain. Mulai dari project kecil dulu. Bikin satu app dan satu shared package, rasain sendiri cache hit yang bikin build selesai dalam milidetik. Terus tambah package seiring kebutuhan. Turborepo bakal scale bareng kamu. Untuk dokumentasi lengkap, kunjungi turbo.build/repo. Komunitasnya aktif dan terus berkembang, jadi kamu gak akan kesulitan nyari bantuan kalo nemu masalah.

Selamat Datang