# Panduan Orkestrasi Turborepo

Monorepo KeluargaMart menggunakan **Turborepo v2** untuk mengorkestrasi pipeline eksekusi (build, test, lint, dev) di seluruh workspace pnpm.

---

## 1. Konfigurasi `turbo.json`

File konfigurasi root `turbo.json` mendefinisikan hubungan antar-task dan strategi caching:

```json
{
  "$schema": "https://turbo.build/schema.json",
  "ui": "tui",
  "tasks": {
    "build": {
      "dependsOn": ["^build"],
      "inputs": ["$TURBO_DEFAULT$", ".env*"],
      "outputs": ["dist/**", ".output/**", ".next/**", ".nuxt/**"]
    },
    "test": {
      "dependsOn": ["^build"],
      "inputs": ["$TURBO_DEFAULT$"]
    },
    "lint": {
      "dependsOn": ["^build"],
      "inputs": ["$TURBO_DEFAULT$"]
    },
    "typecheck": {
      "dependsOn": ["^build"],
      "inputs": ["$TURBO_DEFAULT$"]
    },
    "dev": {
      "cache": false,
      "persistent": true
    }
  }
}
```

---

## 2. Penjelasan Konsep Penting

### A. Topological Dependency (`dependsOn: ["^build"]`)
Simbol caret (`^`) memberitahu Turborepo bahwa sebelum task `build` atau `test` suatu aplikasi dijalankan, Turborepo harus terlebih dahulu mem-build package yang menjadi dependensinya.
- Contoh: Ketika `apps/erp` di-build, Turborepo akan memastikan `@keluargamart/contracts`, `@keluargamart/permissions`, `@keluargamart/utils`, dan `@keluargamart/api-client` telah selesai di-build terlebih dahulu.

### B. Output Artifacts (`outputs`)
Turborepo melacak folder output build:
- `dist/**` untuk Vite (ERP, POS, packages).
- `.output/**` untuk Nuxt 4 (B2B).
Jika tidak ada perubahan kode pada source file (`inputs`), eksekusi build berikutnya akan mengambil hasil kompilasi langsung dari cache dalam waktu milidetik (**Cache Hit**).

### C. Persistent Tasks (`dev`)
Task `dev` disetel `cache: false` dan `persistent: true` karena merupakan server interaktif berjangka panjang (*long-running process*) yang tidak boleh di-cache atau berhenti secara otomatis.

---

## 3. Contoh Penggunaan Perintah Filter

Turborepo mendukung penyaringan task berbasis package atau path:

```bash
# 1. Jalankan test hanya untuk packages/utils
pnpm exec turbo run test --filter=@keluargamart/utils

# 2. Build ERP beserta seluruh shared packages yang dibutuhkannya
pnpm exec turbo run build --filter=@keluargamart/erp...

# 3. Jalankan test untuk semua komponen yang berubah sejak commit main
pnpm exec turbo run test --filter=...[origin/main]

# 4. Jalankan typecheck di semua project Nuxt / TypeScript
pnpm exec turbo run typecheck
```

---

## 4. Reset & Troubleshooting Cache

Jika Anda ingin memaksa Turborepo menjalankan build ulang dari awal tanpa menggunakan cache:

```bash
# Opsi 1: Bypass cache saat eksekusi
pnpm exec turbo run build --force

# Opsi 2: Bersihkan direktori cache lokal
pnpm exec turbo clean
rm -rf .turbo apps/*/.turbo packages/*/.turbo
```