Belajar Zellij - Layouts KDL & Project Workspaces

#Pendahuluan

Selamat datang di episode 10 series Belajar Zellij! Di episode 9 kalian belajar mengatur tombol — keybinding yang personal dan bebas konflik. Sekarang giliran mengatur ruangan: Layouts KDL dan project workspaces. Kalau keybinding adalah cara menekan shortcut, layout adalah cetak biru workspace: siapa duduk di mana, direktori apa yang dibuka, perintah apa yang dijalankan, dan bagaimana semuanya tersusun dalam satu file yang bisa dibagikan.

Ada lima hal yang akan kalian kuasai di episode ini: (1) sintaks dasar layout KDL dengan node layout, pane, dan tab, (2) menentukan ukuran, arah split, cwd, environment, dan command, (3) menjalankan layout dengan zellij -l dan mengatur default layout, (4) tiga studi kasus nyata: workspace developer, server admin, dan layout dengan command plus floating pane, serta (5) pola-pola yang menghindari kesalahan umum. Zellij memakai KDL sebagai bahasa konfigurasi — tidak ada YAML lagi sejak 0.40.

Mengapa layout penting? Tanpa layout, setiap memulai kerja kalian harus mengatur ulang pane, membuka editor, menjalankan dev server, menata ukuran — lima belas menit yang berulang setiap hari. Dengan layout, seluruh proses menjadi satu perintah. Ini bukan sekadar kenyamanan; ini disiplin: workspace yang deterministik berarti setiap orang di tim, dan setiap mesin, memulai dari titik yang sama. Kalau episode 8 dan 9 adalah fondasi, episode ini adalah kerangka bangunan. Mari mulai.

#Dasar-Dasar Layout KDL

Layout adalah file teks yang mendefinisikan susunan pane dan tab Zellij. Struktur utamanya adalah node global layout, dan di dalamnya hidup node pane dan tab. Sebuah pane bisa berupa shell polos, perintah tertentu, plugin, atau kontainer logis yang menampung pane lain. Atribut split_direction menentukan arah garis pemisah antar anak: "vertical" berarti pane anak berdampingan kiri-kanan, sedangkan "horizontal" menumpuk atas-bawah.

Layout KDL paling sederhana

layout {
    pane split_direction="vertical" {
        pane
        pane
    }
}

Contoh di atas membuka dua pane shell yang berdampingan. Perhatikan bahwa split_direction dipasang pada pane induk dan berlaku untuk anak-anaknya. Layout yang lebih dalam cukup dengan menumpuk node: pane di dalam pane di dalam pane. Setiap pane tanpa command akan menjalankan shell default kalian — biasanya $SHELL — dan setiap pane adalah PTY tersendiri, sama seperti pane yang kalian buat manual dengan Alt n.

Layout dengan tab bertingkat

layout {
    tab name="kod" {
        pane split_direction="vertical" {
            pane
            pane split_direction="horizontal" {
                pane
                pane
            }
        }
    }
    tab name="ops" {
        pane
    }
}

Node tab memungkinkan satu layout membuka beberapa tab sekaligus, lengkap dengan name dan cwd sendiri. Ini persis seperti mendefinisikan "halaman" dalam satu file. Kalau kalian tidak menulis tab sama sekali, semua pane berada di satu tab default. Urutan node menentukan urutan visual, dan atribut focus=true bisa menunjuk pane mana yang menerima fokus pertama kali.

#Ukuran, Posisi, dan Arah

Susunan tanpa ukuran akan dibagi rata oleh Zellij, tetapi dalam praktiknya kalian hampir selalu ingin beberapa pane lebih dominan. Atribut size menerima dua bentuk: angka bulat untuk ukuran tetap dalam satuan karakter, atau string persen seperti "60%" untuk proporsi ruang.

Kombinasi ukuran tetap dan persen

layout {
    pane size="60%" split_direction="vertical" {
        pane focus=true
        pane split_direction="horizontal" {
            pane size=5
            pane
        }
    }
}

Di sini kolom kiri mengambil 60% lebar layar, dan di dalam kolom kanan ada strip kecil setinggi lima baris di atas dan pane lain di bawahnya. Kombinasi size pada level berbeda memberi kalian kendali granular: persen untuk membagi ruang utama, angka tetap untuk strip seperti status monitor atau input bar.

Atribut	Nilai	Fungsi
`split_direction`	`"vertical"` / `"horizontal"`	Arah pemisahan anak
`size`	`4` atau `"60%"`	Ukuran tetap/persen di dalam kontainer
`focus`	`true`	Pane menerima fokus saat layout dimuat
`name`	string	Nama tampilan pane/tab
`borderless`	`true` / `false`	Sembunyikan frame pane
`start_suspended`	`true` / `false`	Mulai command dalam keadaan suspend

Satu aturan penting: size bernilai nol ditolak Zellij, dan nilai harus berupa angka positif atau persen yang valid. Kesalahan kecil di sini hanya akan menghasilkan error parsing yang jelas — ikuti saja pesannya.

Note

Urutan definisi di KDL sama dengan urutan visual. Jika layout terasa "terbalik", periksa arah split pada pane induk: "vertical" menghasilkan anak berdampingan (kiri-kanan), sementara "horizontal" menumpuk (atas-bawah). Mental model yang membantu: bayangkan split_direction sebagai arah garis yang membelah induknya, bukan arah aliran anak.

#Command, cwd, dan Environment

Pane yang hanya membuka shell sering tidak cukup — kalian ingin pane menjalankan perintah tertentu di direktori tertentu dengan environment tertentu. Atribut command menunjuk executable, args berisi argumennya, dan cwd menentukan direktori kerja. Untuk environment per pane, Zellij sejak 0.42 mendukung node env_vars.

Pane command dengan cwd dan env_vars

layout {
    pane cwd="/home/arman/dev/belajar-zellij" split_direction="vertical" {
        pane focus=true
        pane {
            command "npm"
            args "run" "dev"
            env_vars {
                PORT "5173"
                NODE_ENV "development"
            }
        }
    }
}

Contoh ini membuka editor di pane kiri dan menjalankan npm run dev dengan environment yang disuntikkan khusus untuk pane itu. Perilaku cwd mengikuti aturan komposisi: cwd relatif pada pane akan digabung dengan cwd pada tab dan layout, sedangkan cwd absolut menggantikan seluruhnya. Kalian juga bisa menaruh cwd global pada node layout sehingga semua pane berangkat dari direktori yang sama — sangat praktis untuk layout per project.

Ada dua atribut yang sering disalahpahami. start_suspended true membuat command pane menunggu sampai kalian me-resume-nya — berguna untuk memastikan environment ready sebelum perintah berjalan. Sementara itu, pane dengan command tutup otomatis ketika perintahnya keluar. Untuk perintah jangka pendek seperti git status, pane akan menghilang seketika; untuk perintah panjang seperti dev server, pane itu hidup sepanjang server berjalan. Jika kalian ingin pane tetap terbuka setelah command selesai, bungkus command dengan shell — misalnya command "bash" dengan args "-c" "npm run dev; exec $SHELL".

Tip

Jangan jalankan perintah yang langsung selesai di layout — pane-nya akan tertutup begitu perintah keluar dan kalian malah kehilangan ruang. Pilih perintah yang berjalan lama (dev server, tail -f, watcher), atau bungkus perintah pendek dengan shell interaktif supaya pane tetap hidup. Pola command "bash" + args "-c" adalah trik yang dipakai banyak dotfiles di komunitas.

#Menjalankan Layout dan Default Layout

Layout yang sudah ditulis disimpan sebagai file .kdl. Zellij mencari layout di direktori ~/.config/zellij/layouts/ — dan secara default akan memuat file default.kdl dari sana setiap kali memulai session. Untuk layout lain, gunakan flag -l atau --layout dengan nama file tanpa ekstensi, atau path lengkap ke file.

zellij -l dev

Perhatikan perbedaan perilaku sejak 0.44: zellij -l dev di dalam session berjalan akan menambahkan layout sebagai tab baru, sedangkan di luar session akan memulai session baru. Jika kalian selalu ingin session baru, gunakan --new-session-with-layout. Zellij juga menyediakan --layout-string untuk menulis layout langsung di command line tanpa file, dan zellij setup --dump-layout compact untuk menyalin layout bawaan sebagai referensi belajar.

Untuk mengatur layout yang dimuat setiap kali session dimulai, set opsi default_layout pada config.kdl:

Menetapkan default layout di config.kdl

default_layout "dev"

Nilai "dev" merujuk ke ~/.config/zellij/layouts/dev.kdl. Jika file tidak ada, Zellij jatuh ke layout bawaan default. Ini cara tercepat membuat setiap session Zellij kalian selalu dimulai dengan workspace yang sama.

#Studi Kasus: Workspace Developer

Mari satukan semuanya dalam studi kasus pertama: layout untuk pengembangan aplikasi web. Tujuannya: editor di kiri, dev server dan git di kanan — workspace yang langsung produktif tanpa satu pun klik.

Layout workspace developer

layout {
    pane cwd="/home/arman/dev/belajar-zellij" split_direction="vertical" {
        pane size="60%" focus=true
        pane split_direction="horizontal" {
            pane size="50%" {
                command "npm"
                args "run" "dev"
            }
            pane {
                command "lazygit"
            }
        }
    }
}

Dengan layout ini, satu perintah zellij -l dev menghasilkan tiga pane: editor neovim (fokus), npm run dev sebagai dev server, dan lazygit untuk kontrol versi. Karena cwd diletakkan di pane induk, semua anak ikut memakai direktori project. Kalian bisa menambahkan pane keempat untuk log dengan tail -f atau journalctl, dan menambahkannya ke layout ini — Zellij akan membaginya sesuai ukuran yang ditentukan.

#Studi Kasus: Server Admin

Studi kasus kedua adalah layout admin server — sangat berguna untuk memantau mesin produksi atau staging tanpa membuka selusin tab.

Layout server admin

layout {
    pane split_direction="vertical" {
        pane focus=true
        pane split_direction="horizontal" {
            pane command="htop"
            pane command="journalctl" args="-f" "-u" "nginx"
        }
    }
}

Pane kiri adalah shell untuk eksekusi perintah, sementara kanan-atas memantau resource dengan htop dan kanan-bawah mengikuti log nginx dengan journalctl -f. Untuk mesin remote, jalankan layout ini setelah SSH, atau jadikan pane utama sebagai command "ssh" — ingat bahwa command pane otomatis berjalan ulang ketika session di-resurrect, sehingga setelah detach, layout monitoring ini bisa muncul kembali secara mandiri.

Important

Ketika layout dijalankan ulang melalui session resurrection, semua command pane akan dieksekusi lagi dari awal. Ini bagus untuk watcher dan server, tetapi berbahaya untuk perintah yang efeknya tidak idempoten — misalnya migrasi database atau command yang menulis file. Tempatkan perintah berbahaya seperti itu di pane shell biasa, bukan command pane, supaya kalian yang memutuskan kapan menjalankannya.

#Studi Kasus: Command dan Floating Pane

Studi kasus terakhir menunjukkan dua kemampuan yang sering dipadukan: command dengan close_on_exit dan floating pane dengan koordinat persen.

Layout dengan floating pane

layout {
    tab name="main" {
        pane
        floating_panes {
            pane x="25%" y="20%" width="50%" height="30%" {
                command "npm"
                args "run" "dev"
                close_on_exit false
            }
        }
    }
}

Node floating_panes di dalam tab mendefinisikan pane yang melayang di atas pane tiled — mengikuti koordinat x, y, width, dan height dalam persen layar. Atribut close_on_exit false menjaga pane tetap terbuka walau command selesai, sementara tanpa atribut itu pane menutup otomatis ketika perintah keluar. Untuk pane floating yang selalu berada di atas tumpukan, tambahkan pinned true — fitur dari 0.42 yang kita kenal di episode 7. Di luar layout, pola yang sama tersedia di runtime lewat zellij run atau keybinding Run dengan child block berisi floating true.

Pola	Penggunaan
`command` + `close_on_exit false`	Pane pekerja yang bertahan walau command selesai
`floating_panes` + koordinat persen	HUD, picker, atau editor melayang
`pinned true`	Floating pane yang selalu di depan
`start_suspended true`	Command yang menunggu trigger manual

#Kesalahan Umum (Common Pitfalls)

Menulis split_direction dengan nilai yang tidak ada. Zellij hanya menerima "vertical" dan "horizontal" — nilai seperti "right" atau "left" akan ditolak parser. Solusi: ingat bahwa atribut ini mengarahkan garis pemisah, bukan arah anak.
Menaruh perintah pendek di command pane. git status, ls, atau date langsung menutup pane-nya. Solusi: gunakan perintah berjalan lama, atau bungkus dengan bash -c dan exec $SHELL agar pane bertahan.
Mengabaikan komposisi cwd. cwd relatif digabung ke atas; jika tidak ada cwd di induk, pane mulai dari direktori saat Zellij dijalankan. Solusi: tetapkan cwd global pada layout untuk setiap layout per project.
Menyimpan layout di direktori yang salah. zellij -l dev hanya menemukan layout di ~/.config/zellij/layouts/ atau path yang diberikan. Solusi: simpan tanpa ekstensi di direktori tersebut, dan cek lokasi persisnya dengan zellij setup --check.
Command pane yang menghilang dianggap bug. Perilaku default command pane memang menutup diri saat perintah selesai. Solusi: gunakan close_on_exit false, start_suspended, atau bungkus dengan shell interaktif.

Warning

Satu layout menentukan satu session utuh — termasuk command yang langsung mengeksekusi sesuatu. Sebelum memakai layout di mesin produksi atau sebagai default layout, uji dulu di direktori kosong dan baca command-nya baris per baris. Layout yang keliru bisa menimbulkan efek yang jauh lebih besar daripada sekadar tampilan pane yang salah.

#Penutup

Di episode 10 ini kalian telah mengubah Zellij dari terminal workspace yang manual menjadi workspace yang bisa di-script: layout KDL dengan pane dan tab, pengaturan split_direction dan size, command dengan cwd dan env_vars, penjalanan lewat zellij -l, hingga tiga studi kasus nyata — workspace developer dengan editor dan dev server, admin server dengan htop dan journalctl, serta layout dengan command dan floating pane.

Poin yang harus kalian bawa:

Layout KDL = cetak biru: layout, pane, tab, split_direction, size.
cwd mengikuti aturan komposisi; set global pada layout untuk workspace per project.
Command pane menutup otomatis saat perintah keluar — pilih perintah panjang atau bungkus dengan shell.
zellij -l memuat layout; default_layout di config menetapkan layout startup.
Floating pane dengan koordinat persen dan pinned true untuk HUD yang selalu di depan.

Workspace kalian kini bisa lahir dengan satu perintah. Di episode 11 berikutnya, kita merapikan tampilannya: Status Bar, Tab Bar, dan Theme Customization — mengonfigurasi tab-bar, status-bar, compact-bar dengan tooltip, theme spec terbaru, tema bawaan dracula dan catppuccin, sampai custom theme dan auto-switch gelap-terang. Sampai jumpa di episode 11!