oxdraw - alat diagram berbasis kode

 (github.com/RohanAdwankar)
25 poin oleh GN⁺ 2025-10-27 | 1 komentar | Bagikan ke WhatsApp
  • oxdraw adalah alat ‘Diagram as Code’ yang ditulis dengan Rust, dirancang agar diagram berbasis kode dapat diedit secara visual dan dipertahankan dalam bentuk yang dapat direproduksi
  • Diagram ditulis dengan sintaks Mermaid, dan melalui antarmuka web posisi node, warna, garis koneksi, dan lainnya dapat disesuaikan dengan drag-and-drop
  • Perubahan visual disimpan sebagai komentar di dalam file Mermaid, sehingga tetap kompatibel dengan alat Mermaid lainnya
  • Terdiri dari CLI dan editor web berbasis React, serta mendukung rendering via command line dan mode pengeditan real-time
  • Dengan menggabungkan produktivitas diagram generatif berbasis kode dan kebebasan pengeditan visual, alat ini dianggap sebagai alternatif untuk alat GUI seperti Lucidchart

Gambaran proyek

  • Tujuan oxdraw adalah memudahkan pembuatan dan pemeliharaan diagram berkualitas tinggi melalui sintaks deklaratif yang dapat direproduksi
    • Diagram ditulis dengan sintaks Mermaid, sementara penyesuaian visual dilakukan di antarmuka web
    • Perubahan yang dibuat pengguna secara visual diterapkan kembali ke kode sumber, sehingga version control dan otomasi dimungkinkan
  • Perubahan dicatat sebagai komentar (comment) di dalam file Mermaid, sehingga tetap sepenuhnya kompatibel dengan alat lain dalam ekosistem Mermaid
  • Repositori ini terdiri dari CLI berbasis Rust dan antarmuka web berbasis React, dan CLI mengompilasi file .mmd menjadi gambar

Visi proyek

  • Pengembang sebelumnya menggunakan Mermaid untuk membuat diagram arsitektur atau visualisasi codebase, tetapi karena keterbatasan pengeditan detail, mereka harus berpindah ke Lucidchart dan sejenisnya
  • oxdraw bertujuan menggabungkan otomasi berbasis kode dari Mermaid dengan kebebasan visual ala Lucidchart
  • Dengan demikian, alat ini berupaya mempertahankan reproducibility, kolaborasi, dan potensi otomasi dari diagram generatif berbasis kode, sekaligus meningkatkan kualitas visualnya

Cara penggunaan

  • Dapat diinstal melalui Cargo: cargo install oxdraw
  • Merender diagram: oxdraw --input flow.mmd
  • Menjalankan editor interaktif: oxdraw --input flow.mmd --edit
  • CLI menerima file Mermaid sebagai input dan menghasilkan output SVG atau PNG, sementara opsi --edit menjalankan editor web lokal

Penjelasan flag CLI

  • -i, --input : input file sumber Mermaid
  • -o, --output : menentukan lokasi penyimpanan hasil render
  • --png: output dalam format PNG
  • --scale : mengatur skala rendering PNG (default 10.0)
  • --edit: menjalankan editor visual
  • --serve-host / --serve-port : menentukan alamat dan port server editor (default 127.0.0.1:5151)
  • -b, --background-color : menentukan warna latar belakang (khusus SVG)
  • -q, --quiet: menekan output seperti pesan render selesai

Fitur frontend

  • Manipulasi node dan edge
    • Menghapus node atau edge yang dipilih (mendukung tombol Delete/Backspace)
    • Menetapkan dan mereset warna node, border, dan warna teks secara individual
    • Mengatur warna edge, gaya garis (solid/putus-putus), dan arah panah
    • Menambahkan dan menghapus control point yang dapat di-drag pada jalur edge
  • Interaksi kanvas dan editor
    • Saat node di-drag, tampil grid snap dan panduan alignment
    • Memindahkan node dengan Shift+panah
    • Mengubah jalur dengan men-drag handle edge, dan menambah/menghapus handle dengan double-click
    • Mendukung pemindahan per subgraph — node dan edge dalam grup bergerak bersama
    • Panel sumber merefleksikan file Mermaid secara real-time, serta menyediakan autosave dan indikator status (menyimpan/error, dll.)
    • Toolbar atas menampilkan path file saat ini dan status penyimpanan

Susunan teknologi dan lisensi

  • Terdiri dari Rust 55.7%, TypeScript 40.0%, CSS 3.4%, dan lainnya 0.9%
  • Dirilis dengan lisensi MIT, sehingga bebas digunakan dan dimodifikasi
  • Saat ini memiliki 506 Star dan 10 Fork, menunjukkan minat komunitas yang aktif

Penilaian keseluruhan

  • oxdraw menghadirkan pendekatan baru yang menggabungkan otomasi pengelolaan diagram berbasis kode dan kemudahan pengeditan visual yang intuitif
  • Sambil mempertahankan kompatibilitas penuh dengan ekosistem Mermaid, alat ini memanfaatkan performa Rust dan UI interaktif React
  • Alat ini mulai mendapat perhatian sebagai penyedia workflow diagram kolaboratif bagi pengembang maupun desainer

Bacaan terkait

1 komentar

 
GN⁺ 2025-10-27
Komentar Hacker News

  • Ini benar-benar proyek yang keren. Menurut saya, pilihan berbasis Mermaid.js masuk akal karena saat ini itu adalah pustaka diagram deklaratif yang paling populer
    Untuk mendukung tipe diagram yang lebih kompleks, D2 Language juga layak dilirik. Ia menawarkan pendekatan deklaratif yang jauh lebih fleksibel

  • Secara pribadi saya membuat port MacPorts dan sedang memakainya
    Kalau nanti makin sering saya gunakan, saya berencana mengontribusikannya ke repositori resmi MacPorts
    Namun, karena tidak ada tag Git atau rilis GitHub yang terhubung dengan rilis Cargo, proses packaging jadi kurang nyaman
    Untuk sementara saya menyiasatinya dengan menganggap commit tertentu (9ccd9bf53f9a309ccda42b5c17e9c1056493fb90) sebagai rilis 0.1.0
    Port terkait bisa dilihat di sini

  • Proyek ini benar-benar persis seperti yang saya cari. Ada fitur yang sangat ingin saya lihat di solusi diagram deklaratif
    Yaitu fitur popup yang menampilkan informasi tambahan atau diagram bertingkat saat mouse diarahkan ke elemen

    • Ide yang menarik. Saya penasaran, apakah popup itu ditujukan untuk penggunaan pribadi, atau untuk dibagikan ke anggota tim
      Misalnya, apakah Anda ingin membagikan tautan agar diagram dengan popup dan nesting bisa langsung dilihat,
      atau cukup dengan membagikan file .mmd lalu membukanya lewat CLI
      Yang terakhir sepertinya bisa cepat diimplementasikan, tetapi yang pertama mungkin memerlukan self-hosting seperti ngrok atau deployment cloud
      Atau bisa juga menambahkan fitur ekspor ke file HTML agar popup tetap berfungsi tanpa CLI

  • Selamat atas perilisan proyeknya. Menarik melihat bagaimana Anda mendefinisikan relasi dengan sintaks deklaratif sambil memungkinkan kustomisasi yang detail yang tidak bisa dilakukan auto-layout yang ada saat ini
    Namun, di Cargo.toml tertulis lisensinya MIT, tetapi di repositori tidak ada file lisensi
    Akan bagus jika ditambahkan agar bisa langsung dicek di GitHub

    • Untuk meningkatkan tingkat adopsi alat ini, saya sarankan mempertimbangkan hosting. Karena sangat bergantung pada kode sisi server, sepertinya sulit memakai hosting statis gratis
    • File lisensi sudah ditambahkan. Terima kasih sudah memberi tahu

  • Ini benar-benar proyek yang dibutuhkan. Saya biasanya memakai PlantUML, tetapi begitu komponennya lebih dari 5, saya menghabiskan 20~30% waktu hanya untuk menyesuaikan layout
    Pendekatan memakai komentar agar ikut tercermin dalam layout engine terasa menarik. Menjadikan koordinat komponen tertentu sebagai constraint tetap lalu menata sisanya secara otomatis sepertinya akan sangat berguna
    Jika diagram ikut masuk ke version control bersama perubahan kode, maka code review dan pengelolaan arsitektur akan terasa jauh lebih alami

    • Saya juga memakai PlantUML di GitLab, tetapi di GitHub harus memakai Mermaid, dan itu merepotkan
      Kualitas layout Mermaid rendah, dan disayangkan GitHub mengabaikan permintaan dukungan PlantUML
      Tampaknya tingkat adopsi ‘diagrams as code’ ditentukan oleh format yang didukung platform utama
      Daripada membuat standar baru, menurut saya perbaikan seperti rendering berbasis bobot elemen lebih realistis
      Pembahasan terkait juga muncul di diskusi komunitas GitHub

  • Saya sangat berharap PlantUML bisa menyelesaikan masalah seperti ini

  • Ini terasa seperti versi yang diperkuat dari bahasa dot milik Graphviz
    Ia menyediakan variabel dan sintaks yang lebih rapi, tetapi konsep dasarnya mirip
    Lihat dokumentasi Graphviz

  • Mermaid.js punya konsep layout engine
    Seperti @mermaid-js/layout-elk
    Saya penasaran apakah Anda pernah mempertimbangkan untuk mengimplementasikan algoritme Anda sebagai layout engine otomatis untuk Mermaid

  • Proyek yang keren. Saya melihatnya di ponsel dan tombol tambah node tidak terlihat
    Satu fitur lain yang saya harapkan adalah menciutkan node turunan (collapse downstream nodes). Mungkin di luar cakupan, tetapi akan bagus jika ada

    • Saat ini .mmd harus diedit langsung secara manual. Namun menurut saya itu usulan yang bagus
      Fitur menciutkan node turunan juga tampaknya cocok dipadukan dengan fitur animasi yang diminta pengguna lain