Pele: Mermaid ke SVG 500x Lebih Cepat, Bundle 230 kB vs 1,6 MB

Pele adalah library open source berlisensi MIT yang merender sintaks Mermaid menjadi SVG dan mengatur temanya lewat CSS variables. Situs resminya mengklaim bundle 230 kB gzip dibanding 1,6 MB untuk Mermaid.js, waktu render 0,05 sampai 0,3 ms dibanding 6 sampai 82 ms, dan nol dependensi langsung dibanding 23. Pele dikembangkan untuk Obsidian dan mendukung semua tipe diagram bawaan Mermaid 12.1.0.

Kenapa Pele bisa jauh lebih cepat?

Pele tidak membawa seluruh runtime Mermaid.js. Ia menerima sintaks Mermaid, mem-parsing diagram, lalu menghasilkan SVG dengan dependensi langsung nol. Mermaid.js sebaliknya membawa puluhan dependensi dan bekerja dengan model layout yang lebih berat, sehingga bundle dan waktu render ikut membesar.

Perbedaan pendekatan ini menjelaskan selisih ukuran. Mermaid.js menyediakan banyak lapisan: parser, theme engine, renderer untuk berbagai jenis diagram, dan integrasi dengan berbagai lingkungan. Pele memangkas sebagian lapisan itu dan fokus pada keluaran SVG yang bisa ditata lewat CSS.

Namun angka 500 kali lebih cepat perlu dibaca sebagai klaim vendor. Situs Pele membandingkan rentang waktu render, bukan hasil benchmark netral dengan metodologi terbuka. Pada diagram kecil, selisihnya mungkin terasa; pada diagram besar dengan banyak node dan edge, faktor yang menentukan bisa berbeda.

Metrik	Pele	Mermaid.js
Ukuran bundle gzip	230 kB	1,6 MB
Waktu render	0,05 sampai 0,3 ms	6 sampai 82 ms
Dependensi langsung	0	23
Theming	CSS variables	Konfigurasi tema
Layar kecil	Menyesuaikan layout	Menskalakan diagram

Tabel di atas memakai angka dari halaman perbandingan Pele. Kolom Mermaid.js diisi oleh Pele, bukan oleh pengukuran Mermaid sendiri. Untuk keputusan teknis, tetap perlu uji dengan diagram yang benar-benar dipakai, terutama kalau diagramnya besar atau kompleks.

Apakah semua diagram Mermaid didukung?

Situs Pele menyatakan library ini mendukung semua tipe diagram yang dibangun ke dalam Mermaid 12.1.0. Itu mencakup flowchart dan jenis diagram lain yang menjadi bagian dari rilis Mermaid tersebut. Klaim ini penting karena banyak alternatif hanya mendukung sebagian tipe diagram.

Meski begitu, kompatibilitas penuh bukan jaminan hasil visual identik. Dua renderer bisa menghasilkan tata letak yang berbeda untuk sintaks yang sama, terutama pada diagram dengan banyak cabang atau label panjang. Halaman compatibility di situs Pele menyediakan perbandingan sintaks, layout, dan fitur, jadi sebaiknya dicek untuk tipe diagram yang kamu pakai.

Kalau diagram memakai fitur di luar Mermaid 12.1.0, misalnya plugin komunitas atau ekstensi khusus, dukungannya tidak otomatis. Pele mengikuti versi Mermaid yang menjadi acuannya, bukan seluruh ekosistem plugin Mermaid.

Bagaimana cara memasang dan memakai Pele?

Pele tersedia sebagai paket npm dan bisa dipasang dengan npm, pnpm, yarn, atau bun. Setelah terpasang, impor fungsi render, kirim sintaks Mermaid sebagai string, lalu sisipkan SVG hasilnya ke DOM. Tidak ada konfigurasi build khusus yang disebut di halaman utama.

npm install pele

import { render } from 'pele';

const hasil = render('flowchart LR A[Input] --> B[SVG]');
document.querySelector('#diagram').innerHTML = hasil.svg;

Pola pemakaiannya sengaja dibuat sederhana: satu fungsi, satu string Mermaid, satu keluaran SVG. Karena hasilnya SVG biasa, kamu bisa menyimpannya, mengirimkannya lewat API, atau menaruhnya di dalam dokumen statis tanpa menjalankan JavaScript di sisi klien.

Untuk aplikasi yang butuh pembaruan cepat, pendekatan ini menghindari siklus render penuh yang biasanya terjadi saat library diagram menggambar ulang seluruh kanvas. Kalau diagramnya berubah, panggil render lagi dan ganti isi kontainer.

Bagaimana theming bekerja?

Tema diatur lewat CSS variables, bukan lewat objek konfigurasi JavaScript. Halaman Pele mencontohkan variabel seperti --pele-bg, --pele-fg, --pele-muted, --pele-line, --pele-surface, --pele-surface-alt, dan --pele-border. Perubahan warna berlaku tanpa render ulang karena SVG mewarisi nilai variabel dari CSS.

.pele {
  --pele-bg: #fffcf0;
  --pele-fg: #100f0f;
  --pele-line: #100f0f;
  --pele-surface: #f2f0e5;
}

Pendekatan ini cocok untuk situs yang punya mode terang dan gelap. Cukup ganti nilai variabel di selector yang sesuai, dan semua diagram ikut berubah tanpa perlu memanggil render ulang satu per satu. Untuk aplikasi dengan banyak diagram, ini menghemat pekerjaan dan mengurangi risiko kedipan saat tema berganti.

Konsekuensinya, kontrol atas detail visual bergantung pada variabel yang disediakan. Kalau butuh kustomisasi di luar variabel itu, kamu mungkin harus menyentuh SVG hasil render atau menambahkan CSS tambahan. Halaman theming di situs Pele memuat daftar variabel dan contoh tema terang serta gelap.

Apa trade-off-nya?

Trade-off pertama adalah ekosistem. Mermaid.js sudah terpasang di banyak alat dan platform, dengan integrasi resmi dan komunitas yang besar. Pele lebih muda, jadi integrasi pihak ketiga belum sebanyak itu. Kalau alur kerjamu bergantung pada integrasi tertentu, cek dulu apakah Pele bisa menggantikannya.

Trade-off kedua adalah paritas visual. Karena Pele punya mesin layout sendiri, hasil diagram bisa berbeda dari Mermaid.js meski sintaksnya sama. Untuk dokumentasi yang sudah punya standar visual, perbedaan ini perlu dievaluasi sebelum migrasi. Halaman compatibility di situs Pele membantu, tetapi uji langsung dengan diagram sendiri tetap lebih meyakinkan.

Trade-off ketiga adalah kematangan. Pele menyebut dirinya open source dan dipakai untuk Obsidian, dengan lisensi MIT. Itu fondasi yang baik, tetapi ukuran komunitas dan frekuensi rilis belum bisa disamakan dengan Mermaid.js yang sudah bertahun-tahun dipakai. Untuk proyek jangka panjang, lihat aktivitas repo dan riwayat rilis sebelum mengandalkannya.

Trade-off keempat adalah klaim performa. Angka 230 kB dan 0,05 sampai 0,3 ms berasal dari situs Pele. Tanpa benchmark independen, angka itu sebaiknya diperlakukan sebagai indikasi, bukan jaminan. Ukur sendiri dengan diagram yang paling berat di proyekmu.

Kapan sebaiknya memakai Pele?

Pele masuk akal kalau kamu punya banyak diagram Mermaid di halaman yang harus tetap ringan, misalnya dokumentasi statis, blog teknis, atau catatan pribadi di Obsidian. Kemampuan menghasilkan SVG langsung juga berguna untuk pipeline yang ingin menyimpan diagram sebagai file, bukan menggambarnya ulang di browser setiap kali halaman dibuka.

Pele kurang cocok kalau kamu membutuhkan paritas visual persis dengan Mermaid.js, dukungan plugin komunitas, atau integrasi yang sudah matang dengan platform lain. Dalam kasus itu, biaya migrasi dan risiko perbedaan layout lebih besar daripada penghematan ukuran bundle.

Untuk tim yang ingin mencoba, langkah paling murah adalah mengambil sepuluh diagram paling kompleks, merendernya dengan Pele dan Mermaid.js, lalu membandingkan ukuran, waktu render, dan hasil visual. Keputusan berbasis data dari diagram sendiri lebih berguna daripada angka umum di halaman perbandingan.

Apa yang perlu diuji sebelum migrasi?

Uji pertama adalah paritas visual. Ambil diagram yang paling sering dipakai, render dengan Pele dan Mermaid.js, lalu bandingkan tata letak, arah panah, label, dan penanganan teks panjang. Perbedaan kecil pada diagram sederhana bisa menjadi besar pada diagram dengan banyak cabang.

Uji kedua adalah performa di halaman nyata. Ukuran bundle dan waktu render di situs Pele diukur pada kondisi tertentu. Di aplikasi nyata, waktu render dipengaruhi jumlah diagram, kompleksitas, dan waktu inisialisasi. Ukur Largest Contentful Paint atau waktu interaktif sebelum dan sesudah migrasi.

Uji ketiga adalah aksesibilitas. SVG yang dihasilkan perlu punya teks alternatif dan struktur yang bisa dibaca screen reader. Periksa apakah Pele menyediakan atribut ARIA atau apakah kamu perlu menambahkannya sendiri. Ini penting untuk dokumentasi publik.

Uji keempat adalah proses build. Kalau diagram dirender saat build, pastikan pipeline bisa menjalankan Pele di lingkungan CI. Kalau dirender di browser, pastikan ukuran bundle akhir sesuai anggaran performa.

Satu hal yang mudah terlewat adalah lisensi aset dan font. Pele menghasilkan SVG, dan SVG bisa memuat font atau gaya yang punya lisensi sendiri. Kalau diagram dipublikasikan, pastikan font yang dipakai boleh didistribusikan dan tidak menimbulkan masalah lisensi.

Bagaimana Pele dipakai di Obsidian?

Situs Pele menyebut library ini dikembangkan untuk Obsidian agar diagram bisa dirender cepat dan mengikuti tema aplikasi. Itu menjelaskan mengapa theming lewat CSS variables menjadi fokus: Obsidian punya tema terang dan gelap yang bisa diganti pengguna kapan saja.

Untuk pengguna Obsidian, pendekatan ini berarti diagram ikut berubah saat tema berganti, tanpa perlu menyimpan dua versi gambar. Untuk pengembang di luar Obsidian, pola yang sama bisa diterapkan asalkan SVG ditempatkan di dalam konteks CSS yang memiliki variabel Pele.

Namun Pele bukan plugin Obsidian itu sendiri. Ia library rendering yang dipakai oleh plugin atau alat lain. Kalau kamu mencari plugin siap pakai, perlu mencari integrasi terpisah yang membungkus Pele.

Sumber utama

Dokumentasi dan playground ada di pele.run. Kode sumber dan riwayat rilis ada di github.com/kepano/pele, sedangkan spesifikasi sintaks dan tipe diagram yang menjadi acuan ada di mermaid.js.org.

FAQ

Apakah Pele pengganti langsung Mermaid.js?

Untuk sintaks dan banyak tipe diagram, ya. Tetapi hasil layout bisa berbeda dan ekosistem integrasinya lebih kecil. Migrasi perlu diuji dengan diagram nyata, bukan hanya membaca tabel perbandingan.

Apakah Pele gratis untuk proyek komersial?

Ya, Pele dirilis dengan lisensi MIT. Kamu tetap perlu menyertakan notice lisensi dan memeriksa dependensi pihak ketiga kalau mendistribusikan ulang paketnya.

Berapa ukuran bundle Pele sebenarnya?

Situs Pele mengklaim 230 kB gzip, dibandingkan 1,6 MB untuk Mermaid.js. Ukuran aktual di proyekmu bisa berbeda tergantung cara bundling dan bagian library yang dipakai.

Apakah Pele mendukung semua jenis diagram Mermaid?

Situsnya menyatakan semua tipe diagram bawaan Mermaid 12.1.0 didukung. Fitur di luar versi itu, termasuk plugin komunitas, tidak otomatis didukung.

Siapa yang mengembangkan Pele?

Pele dikembangkan untuk Obsidian oleh kepano dan dirilis sebagai proyek open source. Namanya diambil dari Pele, dewi gunung berapi dan api dalam mitologi Hawaii.

Rekomendasi Tools & Layanan

Kalau lo mau langsung praktikkan panduan di atas, dua layanan yang gue pake sehari-hari: free trial Alibaba Cloud buat coba-coba tanpa biaya di awal, dan ECS instance 9th-gen kalau udah siap naik ke VPS production.