Monorepo: apa itu dan cara menyiapkannya dengan pnpm
Monorepo adalah cara menyimpan kode dari banyak proyek dalam satu repositori. Cara lain, yang disebut multi-repo, memberi setiap proyek repositorinya sendiri. Dokumentasi workspace pnpm (buka di tab baru) juga menyebut monorepo sebagai “monolithic repositories”.
Manfaat monorepo
Sebagian manfaat ini dicatat dalam artikel Google tahun 2016 tentang satu repositori untuk seluruh kode (buka di tab baru).
- Berbagi kode: proyek bisa langsung memakai kode proyek lain. Kode tidak perlu disalin ke repositori lain.
- Refaktor skala besar: perubahan yang menyentuh banyak proyek lebih mudah dikerjakan.
- Dependensi lebih sederhana. Artikel Google menyebut manfaat ini untuk kode internalnya. Di pnpm,
catalogdipnpm-workspace.yamlmenyimpan rentang versi dependensi sebagai konstanta yang bisa dipakai ulang. Paket memakainya dengancatalog:, dan ini memudahkan menjaga satu versi untuk setiap dependensi di workspace. - Kolaborasi: tim bisa melihat kode tim lain dan menemukan API yang bisa dipakai ulang.
- Commit atomik: satu commit bisa memuat perubahan di beberapa proyek sekaligus.
Tantangan monorepo
- Ukuran repositori: repositori bisa membesar seiring waktu. GitHub menyarankan ukuran folder
.gittidak lebih dari 10 GB, karena repositori besar memperlambat fetch dan memperpanjang waktu clone. - Kompleksitas build: alat build harus menangani banyak proyek sekaligus. Google menyebut investasi alat sebagai salah satu dari tiga jenis biaya monorepo.
- Satu perubahan bisa merusak paket lain: paket yang memakai
workspace:langsung ikut memakai kode terbaru dari paket itu. - Kontrol akses: izin GitHub berlaku per repositori. CODEOWNERS menentukan siapa yang diminta meninjau perubahan di folder tertentu. Jika sebagian kode harus dibatasi, pertimbangkan repositori terpisah.
- Performa Git: operasi Git bisa melambat pada skala besar. Git punya sparse checkout untuk memuat folder tertentu saja, dan partial clone untuk repositori yang sangat besar.
Menyiapkan monorepo dengan pnpm
pnpm punya fitur workspace bawaan untuk monorepo. Langkah berikut ditulis untuk pnpm 12. Hasilnya ada tiga paket: project-a, project-b, dan shared-utils.
Buat folder root
mkdir my-monorepo
cd my-monorepo
pnpm initpnpm init membuat package.json. Perintah ini juga mengisi kolom packageManager dengan versi pnpm.
Buat pnpm-workspace.yaml
Buat berkas pnpm-workspace.yaml di folder root. Kunci packages berisi pola folder paket.
packages:
- 'packages/*'Pola ini mencocokkan setiap folder satu tingkat di bawah packages/.
Buat folder dan paket
mkdir -p packages/project-a packages/project-b packages/shared-utils
cd packages/project-a
pnpm init
cd ../project-b
pnpm init
cd ../shared-utils
pnpm initNama paket mengikuti nama folder. Folder shared-utils menghasilkan paket bernama shared-utils.
Hubungkan paket lokal
Tulis dependensi ke paket lokal dengan protokol workspace:. Secara bawaan, pnpm mengambil paket dari registry jika protokol ini tidak dipakai.
Tambahkan ini ke packages/project-a/package.json:
{
"dependencies": {
"shared-utils": "workspace:*"
}
}Lalu jalankan pnpm install dari folder root. Perintah itu menautkan shared-utils ke project-a dan membuat pnpm-lock.yaml di root.
workspace:* hanya menerima paket lokal. Saat paket diterbitkan, pnpm mengganti nilai itu dengan nomor versi.
Tambahkan skrip di root
Ganti isi scripts di package.json root dengan ini:
{
"scripts": {
"dev": "pnpm -r --parallel run dev",
"build": "pnpm -r run build",
"test": "pnpm -r run test"
}
}Perintah pnpm -r menjalankan skrip di setiap paket dan melewati folder root. Paket tanpa skrip itu dilewati.
Skrip build dan test berjalan sesuai urutan dependensi. Jadi shared-utils selesai dibangun sebelum project-a.
Skrip dev memakai --parallel. Tanpa flag ini, pnpm menunggu skrip dev milik dependensi selesai sebelum memulai paket yang memakainya. Jika skrip dev itu menjalankan server, skrip itu tidak pernah selesai. Akibatnya, paket yang memakainya tidak pernah mulai.
Skrip test bawaan dari pnpm init selalu gagal dengan pesan Error: no test specified. Ganti skrip itu dengan tes sungguhan di paket yang sudah punya tes, atau hapus di paket yang belum punya. Jika skrip bawaan masih ada, pnpm test berhenti dengan error. Jika tidak ada paket yang punya skrip test, pnpm test selesai tanpa error, tetapi tidak menjalankan tes apa pun.
Alat tambahan
pnpm menangani penautan paket dan menjalankan skrip. Pengaturan tasks (buka di tab baru) menentukan urutan antarskrip saat skrip dijalankan di banyak paket sekaligus.
pnpm 12.4 menambahkan perintah pnpm pipeline (buka di tab baru). Perintah ini hanya menjalankan tugas untuk proyek yang berubah dibanding origin/main. Proyek yang bergantung padanya juga ikut dijalankan. Untuk tugas yang mendeklarasikan outputs, hasil cache dipakai jika tersedia. Perintah ini butuh daftar pipelines di pnpm-workspace.yaml. Fitur ini masih eksperimental, jadi konfigurasi dan keluarannya bisa berubah. Perintah pnpm -r run biasa tidak pernah memakai cache ini.
Turborepo (buka di tab baru) dan Nx (buka di tab baru) juga menyimpan cache hasil tugas. Nx punya nx affected untuk menjalankan hanya tugas yang terdampak perubahan.
Contoh struktur folder
Struktur ini memakai pnpm. Hanya folder yang cocok dengan pola di pnpm-workspace.yaml yang menjadi paket. Jadi tools/ dan docs/ bukan paket pnpm.
my-monorepo/
├── package.json
├── pnpm-workspace.yaml
├── .gitignore
├── README.md
├── packages/
│ ├── project-a/
│ │ ├── package.json
│ │ ├── src/
│ │ │ └── index.js
│ │ └── tests/
│ │ └── index.test.js
│ ├── project-b/
│ │ ├── package.json
│ │ ├── src/
│ │ │ └── index.js
│ │ └── tests/
│ │ └── index.test.js
│ └── shared-utils/
│ ├── package.json
│ └── src/
│ └── utils.js
├── tools/
│ └── build-scripts/
│ └── build.js
└── docs/
├── project-a/
│ └── README.md
└── project-b/
└── README.mdpackages/berisi semua proyek dan paket.project-adanproject-badalah contoh proyek terpisah dalam monorepo.shared-utilsadalah paket yang dipakai proyek lain.tools/berisi skrip build dan utilitas lain yang dipakai di seluruh monorepo.docs/berisi dokumentasi untuk setiap proyek.
Mengelola monorepo dengan GitHub
GitHub punya beberapa fitur untuk mengelola monorepo.
Workflow GitHub Actions
Workflow GitHub Actions bisa dibatasi dengan filter paths di bagian on.push. Dengan filter ini, workflow hanya berjalan saat berkas di folder tertentu berubah. Dokumentasi GitHub Actions tentang filter paths (buka di tab baru) menjelaskan pola yang bisa dipakai.
Aturan branch protection
Aturan branch protection mengatur apa yang boleh masuk ke branch utama. Anda bisa mewajibkan status check lulus atau review sebelum merge. GitHub juga menyediakan rulesets sebagai cara lain untuk mengatur branch.
Berkas CODEOWNERS
Berkas CODEOWNERS menentukan siapa yang diminta meninjau perubahan di folder tertentu. Letakkan di .github/CODEOWNERS. Baris berikut menetapkan tim @org/tim-a sebagai pemilik folder project-a:
/packages/project-a/ @org/tim-aTim pemilik harus berstatus visible (pengaturan visibilitas tim di GitHub) dan punya akses tulis ke repositori, walaupun setiap anggotanya sudah punya akses tulis. Saat pull request yang bukan draft mengubah berkas di folder itu, GitHub otomatis meminta pemilik untuk meninjau. Persetujuan pemilik hanya wajib jika aturan branch mengaktifkan opsi “Require review from Code Owners”.
GitHub Projects
GitHub Projects membantu melacak pekerjaan lintas paket dalam satu tabel atau papan.
Praktik yang baik
-
Pakai Conventional Commits, misalnya
feat(ui): tambahkan tombol salin. Format ini memudahkan pembuatan changelog dan penentuan versi secara otomatis. -
Pasang linter dan formatter, misalnya ESLint dan Prettier, supaya gaya kode tetap konsisten.
-
Otomatiskan sebanyak mungkin lewat GitHub Actions, misalnya untuk pengujian, build, dan deploy.
-
Tulis README yang jelas untuk setiap proyek dan untuk root monorepo.
-
Catat perubahan untuk rilis dengan
pnpm change. Perintah ini membuat berkas Markdown di folder.changeset/. Lalu jalankanpnpm version -runtuk menaikkan versi dan menulis changelog. Alur ini bawaan pnpm. Lihat dokumentasi versioning pnpm (buka di tab baru) untuk detailnya.Berkas itu memakai format Changesets. Jika lebih suka CLI Changesets, pasang
@changesets/clidi root denganpnpm add -Dw @changesets/cli, lalu jalankanpnpm changeset init. Setelah itu,pnpm changesetmembuat changeset danpnpm changeset versionmemperbarui versi dan changelog. Panduannya ada di panduan pnpm tentang Changesets (buka di tab baru).
Kapan memakai monorepo
Menurut saya, monorepo paling berguna untuk proyek yang saling bergantung. Untuk proyek yang berdiri sendiri, multi-repo bisa lebih sederhana.
Studi kasus Google tahun 2018 (buka di tab baru) juga mencatat kelebihan multi-repo: kebebasan memilih alat, serta manfaat kontrol akses dan stabilitas.
