Hyprland 0.55 Pindah ke Lua: Panduan Migrasi Config untuk Linux Desktop 2026

Hyprland 0.55: Perubahan Terbesar dalam 4 Tahun Terakhir

Hyprland baru saja rilis versi 0.55, dan ini bukan release biasa. Setelah 4 tahun pakai format config proprietary yang terus berkembang dan bikin config file makin kompleks, Hyprland akhirnya pindah ke Lua sebagai bahasa konfigurasi default. Ini perubahan paling signifikan sejak Hyprland migrate dari wlroots — bahkan menurut Vaxry (maintainer utama), ini lebih besar dari itu.

Buat lo yang belum kenal: Hyprland itu Wayland compositor yang dynamic tiling, highly customizable, dan punya animasi yang smooth banget. Sekarang punya 37k+ stars di GitHub dan jadi salah satu compositor paling populer di kalangan Linux enthusiast yang suka customizing desktop mereka. Kalau lo pakai Arch Linux, Fedora, atau distro lain yang support Wayland, kemungkinan besar lo udah denger soal Hyprland.

Release 0.55 ini datang dengan beberapa perubahan besar yang gak cuma soal config format. Ada user-defined layouts (bikin layout tiling sendiri), performance improvements yang signifikan, dan tentu saja: Lua-based configuration yang bikin semua hal jadi lebih powerful dan maintainable.

Kenapa Lua? Bukan TOML atau YAML?

Format config Hyprland sebelumnya itu basically key-value pairs dengan bracket notation. Simple, tapi punya keterbatasan serius: gak ada conditional logic, gak ada loops, gak ada variable references, dan gak ada cara untuk generate config secara programmatic. Kalau lo mau setup yang berbeda untuk work vs personal, lo harus maintain 2 file config terpisah yang isinya 90% sama.

Lua solve semua masalah ini dengan elegan:

• Conditional logic — bisa bedain config berdasarkan environment variable, monitor yang terdeteksi, atau waktu. Contoh: auto-switch ke dark mode setelah jam 6 sore.
• Variables & functions — DRY principle untuk config. Definisikan terminal, browser, launcher sekali, pakai di mana-mana. Gak perlu ubah 20 baris kalau mau ganti terminal.
• Looping — generate keybinds atau workspace rules secara programmatic. Kalau lo punya 10 workspace dengan keybind pattern yang sama, cukup loop aja.
• External data — bisa baca file, execute command, dan integrate dengan system lain. Contoh: baca dari file .env untuk dynamic config.
• Error handling — Lua punya proper error messages dengan line numbers, bukan silently fail kayak format lama.
• Library ecosystem — bisa pake library Lua yang udah ada untuk parsing JSON, handling filesystem, dll.

Kalau lo familiar dengan Neovim config (yang juga pakai Lua), transisi ini bakal terasa natural. Kalau belum — ini kesempatan belajar bahasa scripting yang ringan, powerful, dan dipake di banyak game engines dan embedded systems.

Migrasi dari Config Lama ke Lua

Step 1: Backup Config Lama

Sebelum apa-apa, backup dulu. Serius. Jangan skip step ini.

# Backup dulu sebelum apa-apa
cp ~/.config/hypr/hyprland.conf ~/.config/hypr/hyprland.conf.bak
cp -r ~/.config/hypr/ ~/.config/hypr-backup-$(date +%Y%m%d)/

# Verify backup
ls -la ~/.config/hypr-backup-$(date +%Y%m%d)/
echo "Backup done. Original file size: $(wc -l < ~/.config/hypr/hyprland.conf) lines"

Step 2: Pahami Format Baru

Di format lama, config Hyprland itu basically list of key-value pairs:

# FORMAT LAMA (hyprland.conf)
monitor = DP-1,2560x1440@144,0x0,1
monitor = HDMI-A-1,1920x1080@60,2560x0,1

workspace = 1, monitor:DP-1
workspace = 2, monitor:DP-1
workspace = 9, monitor:HDMI-A-1
workspace = 10, monitor:HDMI-A-1

input {
    kb_layout = us
    follow_mouse = 1
    touchpad {
        natural_scroll = true
    }
}

bind = SUPER,Return,exec,alacritty
bind = SUPER,D,exec,wofi --show drun
bind = SUPER,E,exec,thunar

Di format baru, lo pakai Lua tables dan syntax:

-- FORMAT BARU (hyprland.lua)
-- Lebih powerful, lebih readable, lebih maintainable!

-- Definisikan variabel sekali
local terminal = "alacritty"
local browser = "firefox"
local launcher = "wofi --show drun"
local file_manager = "thunar"

-- Monitor configuration
local monitors = {
  { name = "DP-1",     res = "2560x1440@144", pos = "0x0",    scale = 1 },
  { name = "HDMI-A-1", res = "1920x1080@60",  pos = "2560x0", scale = 1 },
}

-- Apply monitor config
for _, mon in ipairs(monitors) do
  hyprland.monitor = {
    name = mon.name,
    config = string.format("%s,%s,%s", mon.res, mon.pos, mon.scale),
  }
end

-- Workspace rules — assign workspace ke monitor
for ws = 1, 5 do
  table.insert(workspace_rules, {
    workspace = tostring(ws),
    monitor = "DP-1",
  })
end
for ws = 9, 10 do
  table.insert(workspace_rules, {
    workspace = tostring(ws),
    monitor = "HDMI-A-1",
  })
end

-- Input configuration
hyprland.input = {
  kb_layout = "us",
  follow_mouse = 1,
  touchpad = { natural_scroll = true },
}

-- Keybinds — DRY dengan loop!
hyprland.binds = {
  { "SUPER", "Return", "exec", terminal },
  { "SUPER", "D",      "exec", launcher },
  { "SUPER", "E",      "exec", file_manager },
  { "SUPER", "B",      "exec", browser },
}

-- Auto-generate workspace keybinds (1-10)
for i = 1, 10 do
  hyprland.binds[#hyprland.binds+1] = {
    "SUPER", tostring(i), "workspace", tostring(i)
  }
  hyprland.binds[#hyprland.binds+1] = {
    "SUPER SHIFT", tostring(i), "movetoworkspace", tostring(i)
  }
end

Step 3: Migrasi Monitor Config

Ini bagian yang paling sering bikin orang bingung. Di format lama, monitor config itu comma-separated string. Di Lua, jadi table:

-- Migrasi monitor config
-- FORMAT LAMA:
-- monitor = DP-1,2560x1440@144,0x0,1
-- monitor = HDMI-A-1,1920x1080@60,2560x0,1

-- FORMAT BARU:
local monitor_configs = {
  { name = "DP-1",     mode = "2560x1440@144", position = "0x0",    scale = 1 },
  { name = "HDMI-A-1", mode = "1920x1080@60",  position = "2560x0", scale = 1 },
}

for _, mon in ipairs(monitor_configs) do
  hyprland.monitor = {
    name = mon.name,
    config = string.format("%s,%s,%s", mon.mode, mon.position, mon.scale),
  }
end

-- Dynamic monitor detection
-- Kalau lo gak yakin nama monitor-nya, bisa detect otomatis:
local output = io.popen("hyprctl monitors -j"):read("*a")
local monitors_json = require("json").decode(output)
for _, mon in ipairs(monitors_json) do
  print("Detected: " .. mon.name .. " (" .. mon.width .. "x" .. mon.height .. ")")
end

Step 4: Conditional Config

Ini killer feature yang gak bisa dilakukan di format lama:

-- Conditional: bedain config kalau di work laptop
if os.getenv("WORK_MODE") == "1" then
  -- Work mode: fewer workspaces, slack always open
  terminal = "kitty"
  hyprland.binds[#hyprland.binds+1] = {
    "SUPER SHIFT", "S", "exec", "slack"
  }
  hyprland.binds[#hyprland.binds+1] = {
    "SUPER SHIFT", "Z", "exec", "zoom"
  }
else
  -- Personal mode: more workspaces, discord
  hyprland.binds[#hyprland.binds+1] = {
    "SUPER SHIFT", "D", "exec", "discord"
  }
end

-- Time-based config
local hour = tonumber(os.date("%H"))
if hour >= 18 or hour < 6 then
  -- Night mode: darker colors, lower brightness
  hyprland.general = {
    col.active_border = "rgba(333333aa)",
    col.inactive_border = "rgba(595959aa)",
  }
  os.execute("brightnessctl set 40%")
else
  -- Day mode
  hyprland.general = {
    col.active_border = "rgba(33ccffee)",
    col.inactive_border = "rgba(595959aa)",
  }
end

Fitur Baru Lainnya di 0.55

Selain Lua config, Hyprland 0.55 juga bring beberapa fitur baru yang signifikan:

Troubleshooting Umum

Beberapa masalah yang sering muncul saat migrasi dan cara solve-nya:

• "Config not found" — pastiin file ada di ~/.config/hypr/hyprland.lua (bukan .conf). Kalau lo masih punya .conf, rename dulu atau hapus supaya Hyprland generate .lua yang baru.
• Syntax error — jalankan luac -p hyprland.lua untuk cek syntax sebelum restart Hyprland. Error message-nya lumayan jelas dan kasih tau line number.
• Monitor gak ke-detek — pastikan nama monitor di Lua match dengan output hyprctl monitors. Nama monitor sensitif case dan bisa berubah kalau lo plug/unplug cables.
• Keybind gak work — format baru pakai table array ({"SUPER", "Return", "exec", "alacritty"}), bukan comma-separated string. Pastikan setiap keybind adalah array of strings.
• Variables undefined — kalau lo pake variable yang belum didefinisikan, Lua akan error. Pastikan semua variable didefinisikan sebelum dipakai.
• Plugin compatibility — beberapa plugin lama mungkin belum support Lua config. Cek plugin documentation sebelum upgrade.

Worth the Switch?

Buat lo yang udah nyaman dengan config lama, migrasi ke Lua itu optional — Hyprland tetap support format .conf untuk backward compatibility. Tapi kalau lo punya setup kompleks (multi-monitor, conditional configs, atau banyak keybinds repetitif), Lua bakal save lo banyak waktu dan bikin config lebih maintainable.

Pengalaman gue setelah migrasi: config gue yang dulu 200 baris format .conf jadi 80 baris Lua — lebih pendek, lebih readable, dan lebih gampang diubah. Plus, bisa pake Neovim-style editing untuk config Hyprland. Win-win.

Rekomendasi gue: mulai dari yang kecil. Coba migrasi keybinds dulu (paling gampang), lihat benefit-nya, baru migrasi bagian lain. Jangan coba migrasi semua sekaligus — itu recipe untuk frustration.