git:20260720.931feca to git:20260729.f16bff5

172 added, 112 removed. Audit A to A.

---

name: monorepo-architect

description: "Expert guide for designing and managing scalable monorepos using Turborepo, pnpm workspaces, and shared packages / Panduan ahli untuk merancang dan mengelola monorepo skalabel menggunakan Turborepo dan pnpm workspaces."

- author: "Antigravity"

+ author: "Roedy Rustam"

---

- # Monorepo & Workspace Architect

+ # Monorepo Architect (Turborepo 2.x / Moon Edition)

[English](#english) | [Bahasa Indonesia](#bahasa-indonesia)

---

## English

- ### Overview

- The **Monorepo & Workspace Architect** skill provides best practices for setting up, managing, and scaling a monorepo architecture. It focuses on using modern tooling like **Turborepo** and **pnpm workspaces** to handle multiple applications and shared packages within a single Git repository.

+ ### Description

+ Expert guide for designing and managing scalable monorepos. Covers **Turborepo 2.x** (the 2026 standard for JS/TS monorepos), **moon** (polyglot task runner for teams mixing JS + Rust + Go), **pnpm workspaces**, shared package design, incremental builds, remote caching, and CI/CD pipeline optimization.

### Trigger Conditions

- Use this skill when:

- - The user wants to split a monolithic application into multiple apps (e.g., public site, admin dashboard, API).

- - The user needs to share UI components, TypeScript types, or utility functions across different projects.

- - The user is setting up `turbo.json` or `pnpm-workspace.yaml`.

- - The user is facing dependency issues or slow build times in a large repository.

+ - Managing a codebase with multiple apps and shared packages.

+ - Setting up a monorepo for a SaaS with separate `web`, `admin`, `api`, and `packages`.

+ - Optimizing build and test times with remote caching.

+ - Sharing TypeScript types, UI components, or utility functions across apps.

+ - Migrating from a multi-repo setup to a monorepo.

- ### Core Architecture Guidelines

+ ### Tool Selection Guide (2026)

- #### 1. Folder Structure

- Maintain a strict separation between deployable applications (`apps/`) and shared libraries (`packages/`).

+ | Tool | Best For | Language Agnostic |

+ |---|---|---|

+ | **Turborepo 2.x** | JS/TS monorepos (Next.js, Vite, Node) | ❌ (JS focused) |

+ | **moon** | Polyglot teams (JS + Go + Rust + Python) | ✅ |

+ | **Nx** | Enterprise, Angular/React, plugin ecosystem | ❌ (JS focused) |

+ | **Bazel** | Very large orgs, hermetic builds | ✅ |

- ```text

- .

+ ### Turborepo 2.x — Standard JS Monorepo

+ #### Repository Structure

+ ```

+ my-saas/

├── apps/

- │ ├── web/ # Main public-facing application (Next.js)

- │ ├── admin/ # Internal admin dashboard (Vite/React)

- │ └── api/ # Backend API services (Node/Bun/Rust)

+ │ ├── web/ # Next.js 15 main app

+ │ ├── admin/ # Next.js 15 super admin (subdomain)

+ │ └── api/ # Hono/Fastify backend

├── packages/

- │ ├── ui/ # Shared React components (Tailwind, shadcn)

- │ ├── types/ # Shared TypeScript interfaces & DTOs

- │ ├── config-eslint/ # Shared ESLint configurations

- │ ├── config-ts/ # Shared tsconfig.json bases

- │ └── db/ # Database schema and ORM client (Prisma/Drizzle)

- ├── turbo.json # Turborepo configuration

+ │ ├── ui/ # Shared Tailwind v4 components

+ │ ├── db/ # Drizzle ORM schema + queries

+ │ ├── auth/ # Auth utilities (session, JWT)

+ │ ├── email/ # Email templates (React Email)

+ │ └── tsconfig/ # Shared TypeScript configs

+ ├── turbo.json

├── pnpm-workspace.yaml

└── package.json

```

- #### 2. Workspace Management (pnpm)

- Always prefer `pnpm` for monorepos due to its strict dependency resolution and speed.

- - Define `pnpm-workspace.yaml` explicitly:

- ```yaml

- packages:

- - "apps/*"

- - "packages/*"

- ```

- - Use the `workspace:*` protocol when linking internal packages to ensure the latest local version is always used.

- #### 3. Turborepo Configuration (`turbo.json`)

- Maximize build cache and parallel execution. Ensure inputs and outputs are correctly defined.

+ #### turbo.json (v2 Syntax)

```json

{

"$schema": "https://turbo.build/schema.json",

- "globalDependencies": ["**/.env.*local"],

+ "ui": "tui",

"tasks": {

"build": {

"dependsOn": ["^build"],

+ "inputs": ["$TURBO_DEFAULT$", ".env*"],

"outputs": [".next/**", "!.next/cache/**", "dist/**"]

- "lint": {

- "dependsOn": ["^lint"]

- },

"dev": {

"cache": false,

"persistent": true

+ },

+ "test": {

+ "dependsOn": ["^build"],

+ "inputs": ["src/**", "test/**", "vitest.config.*"]

+ },

+ "lint": {

+ "inputs": ["src/**", "*.config.*", ".eslintrc*"]

+ },

+ "typecheck": {

+ "dependsOn": ["^build"]

+ },

+ "db:generate": {

+ "cache": false

}

```

- #### 4. The Shared UI Package (`@repo/ui`)

- When sharing UI components (e.g., Tailwind CSS + React):

- - Do not transpile the UI package locally; let the consumer apps (Next.js/Vite) transpile it. This avoids complex build steps in the `packages/ui` folder.

- - Ensure the consumer app's `tailwind.config.ts` includes the UI package in its `content` path to scan for classes.

- - Use `transpilePackages: ["@repo/ui"]` in Next.js `next.config.mjs`.

+ #### pnpm-workspace.yaml

+ ```yaml

+ packages:

+ - "apps/*"

+ - "packages/*"

+ ```

- #### 5. CI/CD & Remote Caching

- - Utilize Vercel Remote Cache or GitHub Actions cache to drastically reduce CI build times.

- - Only run tests and deployments on packages that have changed by using `turbo run build --filter=...[origin/main]`.

+ #### Remote Caching (Vercel Remote Cache)

+ ```bash

+ # Authenticate with Vercel Remote Cache

+ npx turbo login

+ npx turbo link

+ # Or self-hosted with Turborepo Remote Cache

+ TURBO_TEAM=my-team TURBO_TOKEN=xxx turbo build

+ ```

+ #### Shared UI Package (`packages/ui`)

+ ```json

+ // packages/ui/package.json

+ {

+ "name": "@myapp/ui",

+ "version": "0.0.0",

+ "private": true,

+ "exports": {

+ "./button": {

+ "import": "./src/button.tsx",

+ "types": "./src/button.tsx"

+ },

+ "./card": {

+ "import": "./src/card.tsx",

+ "types": "./src/card.tsx"

+ }

+ },

+ "peerDependencies": {

+ "react": "^19.0.0",

+ "react-dom": "^19.0.0"

+ }

+ ```

+ #### Internal Package Pattern (No Build Step)

+ Use `"exports"` pointing to source files directly — Turborepo compiles them as part of the consuming app:

+ ```json

+ // packages/db/package.json

+ {

+ "name": "@myapp/db",

+ "exports": {

+ ".": {

+ "import": "./src/index.ts",

+ "types": "./src/index.ts"

+ }

+ },

+ "devDependencies": {

+ "drizzle-orm": "latest",

+ "drizzle-kit": "latest"

+ }

+ ```

+ ### moon — Polyglot Task Runner

+ For teams mixing JavaScript, Go, Rust, and Python in one repo:

+ ```yaml

+ # .moon/workspace.yml

+ projects:

+ - "apps/*"

+ - "packages/*"

+ - "services/*" # Go/Rust microservices

+ vcs:

+ manager: "git"

+ defaultBranch: "main"

+ ```

+ ```yaml

+ # apps/api/moon.yml (Go service)

+ language: "go"

+ type: "application"

+ tasks:

+ build:

+ command: "go build -o ./bin/api ./cmd/api"

+ inputs: ["src/**/*.go", "go.mod"]

+ outputs: ["bin/api"]

+ test:

+ command: "go test ./..."

+ ```

+ ### CI/CD Optimization

+ ```yaml

+ # .github/workflows/ci.yml

+ - name: Build & Test (Turborepo)

+ run: |

+ npx turbo run build test lint typecheck \

+ --filter="...[origin/main]" \ # Only changed packages

+ --cache-dir=".turbo"

+ env:

+ TURBO_TOKEN: ${{ secrets.TURBO_TOKEN }}

+ TURBO_TEAM: ${{ vars.TURBO_TEAM }}

+ ```

---

## Bahasa Indonesia

- ### Ringkasan

- Skill **Monorepo & Workspace Architect** memberikan praktik terbaik untuk menyiapkan, mengelola, dan menskalakan arsitektur monorepo. Skill ini berfokus pada penggunaan alat modern seperti **Turborepo** dan **pnpm workspaces** untuk mengelola beberapa aplikasi dan paket (library) yang digunakan bersama dalam satu repositori Git.

+ ### Deskripsi

+ Panduan ahli untuk merancang dan mengelola monorepo yang skalabel. Mencakup **Turborepo 2.x** (standar 2026 untuk monorepo JS/TS), **moon** (task runner poliglot untuk tim yang memadukan JS + Rust + Go), **pnpm workspaces**, desain shared package, incremental build, remote caching, dan optimasi pipeline CI/CD.

### Kondisi Pemicu

- Gunakan skill ini ketika:

- - Pengguna ingin memecah aplikasi monolitik menjadi beberapa aplikasi terpisah (misalnya: situs publik, dasbor admin, API).

- - Pengguna perlu membagikan komponen UI, tipe TypeScript, atau fungsi utilitas ke berbagai proyek berbeda.

- - Pengguna sedang mengonfigurasi `turbo.json` atau `pnpm-workspace.yaml`.

- - Pengguna menghadapi masalah dependensi atau waktu *build* yang lambat di repositori yang besar.

- ### Panduan Arsitektur Inti

+ - Mengelola codebase dengan banyak aplikasi dan shared package.

+ - Menyiapkan monorepo untuk SaaS dengan `web`, `admin`, `api`, dan `packages` terpisah.

+ - Mengoptimalkan waktu build dan test dengan remote caching.

+ - Berbagi TypeScript types, komponen UI, atau utilitas antar aplikasi.

+ - Migrasi dari multi-repo ke monorepo.

- #### 1. Struktur Folder

- Pertahankan pemisahan yang ketat antara aplikasi yang dapat di-deploy (`apps/`) dan library yang dibagikan (`packages/`).

+ ### Panduan Pemilihan Tool (2026)

+ - **Turborepo 2.x**: Standar untuk monorepo JS/TS — cepat, zero-config, remote cache bawaan.

+ - **moon**: Untuk tim poliglot yang memadukan JS, Go, Rust, Python dalam satu repo.

+ - **Nx**: Untuk enterprise dengan ekosistem plugin yang kaya.

- ```text

- .

- ├── apps/

- │ ├── web/ # Aplikasi utama untuk publik (Next.js)

- │ ├── admin/ # Dasbor admin internal (Vite/React)

- │ └── api/ # Layanan backend API (Node/Bun/Rust)

- ├── packages/

- │ ├── ui/ # Komponen React bersama (Tailwind, shadcn)

- │ ├── types/ # Interface & DTO TypeScript bersama

- │ ├── config-eslint/ # Konfigurasi ESLint bersama

- │ ├── config-ts/ # Base tsconfig.json bersama

- │ └── db/ # Skema database dan ORM client (Prisma/Drizzle)

- ├── turbo.json # Konfigurasi Turborepo

- ├── pnpm-workspace.yaml

- └── package.json

- ```

+ ### Struktur Repositori

+ Pisahkan `apps/` (aplikasi yang dapat di-deploy) dari `packages/` (shared library internal):

+ - `apps/web` — Next.js utama

+ - `apps/admin` — Dashboard Super Admin (subdomain terpisah)

+ - `apps/api` — Backend API

+ - `packages/ui` — Komponen UI bersama (Tailwind v4)

+ - `packages/db` — Skema Drizzle ORM + query

+ - `packages/auth` — Utilitas auth

- #### 2. Manajemen Workspace (pnpm)

- Selalu prioritaskan `pnpm` untuk monorepo karena kecepatan dan resolusi dependensinya yang ketat.

- - Definisikan `pnpm-workspace.yaml` secara eksplisit:

- ```yaml

- packages:

- - "apps/*"

- - "packages/*"

- ```

- - Gunakan protokol `workspace:*` (misal: `"@repo/ui": "workspace:*"`) saat menautkan paket internal agar versi lokal terbaru selalu digunakan.

+ ### Turborepo 2.x — Sintaksis Baru

+ Turborepo 2.x memperkenalkan TUI interaktif (`"ui": "tui"`), sintaksis `tasks` yang lebih ekspresif, dan caching yang lebih granular dengan `inputs`/`outputs`.

- #### 3. Konfigurasi Turborepo (`turbo.json`)

- Maksimalkan penggunaan *cache* dan eksekusi paralel. Pastikan `inputs` dan `outputs` terdefinisi dengan benar untuk menghindari *cache miss*.

- ```json

- {

- "$schema": "https://turbo.build/schema.json",

- "globalDependencies": ["**/.env.*local"],

- "tasks": {

- "build": {

- "dependsOn": ["^build"],

- "outputs": [".next/**", "!.next/cache/**", "dist/**"]

- },

- "lint": {

- "dependsOn": ["^lint"]

- },

- "dev": {

- "cache": false,

- "persistent": true

- }

- ```

+ ### Pola Internal Package (Tanpa Build Step)

+ Arahkan `exports` langsung ke file sumber TypeScript — Turborepo mengkompilasi sebagai bagian dari aplikasi yang mengonsumsinya. Ini menghilangkan kebutuhan langkah build terpisah untuk setiap package.

- #### 4. Paket UI Bersama (`@repo/ui`)

- Saat berbagi komponen UI (misal: Tailwind CSS + React):

- - Jangan lakukan proses *transpile* (build) pada paket UI secara lokal; biarkan aplikasi konsumen (Next.js/Vite) yang melakukan *transpile*. Ini menghindari kerumitan konfigurasi *build* di dalam folder `packages/ui`.

- - Pastikan `tailwind.config.ts` di aplikasi konsumen menyertakan path paket UI di bagian `content` agar Tailwind bisa memindai *utility classes*-nya.

- - Gunakan konfigurasi `transpilePackages: ["@repo/ui"]` di `next.config.mjs` Next.js.

+ ### moon — Task Runner Poliglot

+ Moon mendukung proyek dalam bahasa yang berbeda (Go, Rust, JS) dalam satu workspace, masing-masing dengan konfigurasi `moon.yml`-nya sendiri.

- #### 5. CI/CD & Remote Caching

- - Manfaatkan *Vercel Remote Cache* atau *GitHub Actions cache* untuk memangkas waktu *build* di CI secara drastis.

- - Hanya jalankan pengujian dan *deployment* pada paket yang mengalami perubahan dengan menggunakan perintah `turbo run build --filter=...[origin/main]`.

+ ### Optimasi CI/CD

+ Gunakan flag `--filter="...[origin/main]"` Turborepo untuk hanya membangun dan menguji package yang berubah sejak commit terakhir. Gunakan remote cache Vercel atau self-hosted untuk berbagi cache antar runner CI.