Capacitor Live Reload di Android dari Windows dan Linux

Live reload mengubah loop build, sync, dan run yang lambat menjadi cukup save dan lihat. Di Mac, flag Capacitor CLI --live-reload biasanya langsung jalan. Di Windows dan Linux flag yang sama juga berfungsi, tapi firewall, networking emulator, dan USB routing sering menyebabkan laporan “tidak bisa reload”. Panduan ini membahas setiap kasus tersebut.

Cara kerja live reload di Capacitor

Aplikasi native biasanya memuat data dist/ dari dalam APK. Dengan server.url set, WebView akan memuat dari URL, yaitu Vite atau dev server framework Anda. Hot module replacement kemudian bekerja persis seperti di browser desktop. Tidak ada bagian native yang berubah; hanya origin halamannya saja.

Dua konsekuensinya:

• Perangkat butuh akses jaringan ke komputer Anda.
• Plain http:// butuh cleartext: true, karena Android memblokir cleartext traffic secara default.

Opsi A: flag CLI

Capacitor CLI dapat menyetel ini untuk satu kali jalan:

bun run dev -- --host 0.0.0.0 &
bunx cap run android --live-reload --host 192.168.1.20 --port 5173

Ganti host dengan LAN IP komputer Anda. CLI akan menulis config sementara, menjalankan app, lalu mengembalikan config tersebut. Jika dev server Anda menggunakan port berbeda, sertakan juga.

Ini adalah cara tercepat. Sisa panduan ini menggunakan konfigurasi eksplisit, yang lebih mudah di-debug dan kompatibel dengan dev server framework apa pun.

Opsi B: konfigurasi eksplisit

Jalankan dev server yang terikat ke semua interface:

# Vite
bun run dev -- --host 0.0.0.0
# Angular
bunx ng serve --host 0.0.0.0
# Next.js
bun run dev -- -H 0.0.0.0

Lalu buat konfigurasi Capacitor khusus dev. Capacitor membaca capacitor.config.ts, jadi aktifkan environment variable:

import type { CapacitorConfig } from '@capacitor/cli';

const liveReloadUrl = process.env.CAP_LIVE_RELOAD_URL;

const config: CapacitorConfig = {
  appId: 'com.example.app',
  appName: 'my-app',
  webDir: 'dist',
  ...(liveReloadUrl
    ? { server: { url: liveReloadUrl, cleartext: true } }
    : {}),
};

export default config;

Jalankan dengan variabel yang sudah diatur:

CAP_LIVE_RELOAD_URL=http://10.0.2.2:5173 bunx cap sync android
bunx cap run android

Di Windows PowerShell:

$env:CAP_LIVE_RELOAD_URL="http://10.0.2.2:5173"; bunx cap sync android
bunx cap run android

Tanpa variabel tersebut, cap sync menulis konfigurasi normal dan release build tetap aman.

Emulator: gunakan 10.0.2.2

Di dalam emulator Android, 10.0.2.2 adalah komputer Anda. Ini berfungsi di Windows dan Linux tanpa perlu mengubah firewall, karena traffic tidak pernah keluar dari mesin. Jika masih gagal, pastikan dev server terikat ke 0.0.0.0 dan bukan hanya itu 127.0.0.1; server yang terikat ke loopback tidak dapat diakses dari jaringan virtual emulator.

HP USB: adb reverse

Opsi paling bersih untuk perangkat fisik, tanpa perlu Wi-Fi maupun aturan firewall:

adb reverse tcp:5173 tcp:5173

Sekarang localhost:5173 di HP mengarah ke komputer Anda. Atur URL-nya sebagai berikut:

CAP_LIVE_RELOAD_URL=http://localhost:5173 bunx cap sync android

adb reverse akan terhapus saat perangkat menyambung ulang, jadi jalankan lagi setelah mencabut kabel. CLI bisa melakukannya untuk Anda: bunx cap run android --live-reload --host localhost --port 5173 --forwardPorts 5173:5173. Pengguna Linux butuh aturan udev dari panduan setup Linux sebelum adb dapat mendeteksi HP tersebut.

HP Wi-Fi: IP LAN plus firewall

Jika USB tidak memungkinkan, gunakan LAN IP komputer Anda dan buka portnya.

Find the IP:

# Linux
ip -4 addr show | grep inet
# Windows
ipconfig

Buka port di Windows. Melalui PowerShell (Run as Administrator):

netsh advfirewall firewall add rule name="Vite dev server" dir=in action=allow protocol=TCP localport=5173

Profil jaringan Public di Windows memblokir koneksi masuk meski sudah ada rule; ubah profil Wi-Fi ke Private di Settings jika ponsel tetap tidak bisa terhubung.

Di Linux dengan ufw:

sudo ufw allow 5173/tcp

Di Fedora dengan firewalld:

sudo firewall-cmd --add-port=5173/tcp

Kemudian:

CAP_LIVE_RELOAD_URL=http://192.168.1.20:5173 bunx cap sync android
bunx cap run android

Kedua perangkat harus berada di subnet yang sama. Jaringan Guest Wi-Fi sering mengisolasi client, yang gejalanya mirip masalah firewall.

Spesifikasi WSL2

Saat Vite berjalan di dalam WSL2, host Windows tidak otomatis mengekspos port. Aktifkan mirrored networking di .wslconfig atau tambahkan port proxy di Windows. Detailnya ada di panduan WSL2.

Masalah websocket HMR

Halaman sudah dimuat tapi perubahan tidak muncul? Websocket HMR mencoba terhubung ke host yang salah. Beritahu Vite alamat publiknya:

// vite.config.ts
export default defineConfig({
  server: {
    host: '0.0.0.0',
    hmr: {
      host: '192.168.1.20', // or 10.0.2.2 for the emulator
      port: 5173,
    },
  },
});

Angular dan Next.js punya opsi yang setara; gejalanya sama dan solusinya adalah menetapkan host websocket.

Debugging dengan Chrome DevTools

Buka chrome://inspect di Chrome atau Edge pada komputer Anda. WebView akan muncul di bawah perangkat dengan URL dev server. Anda bisa mengakses console, network, sources, dan breakpoint, baik di Windows maupun Linux. Jika perangkat tidak muncul, cek adb devices dan pastikan USB debugging sudah diizinkan.

Jangan pernah merilis konfigurasi dev

Release build dengan server.url yang diatur akan memuat dari mesin yang tidak ada, sehingga aplikasi menampilkan layar kosong. Cegah hal ini:

• Gunakan pola environment variable di atas agar konfigurasi default tidak memiliki server blok.
• Tambahkan CI check yang akan gagal jika build android/app/src/main/assets/capacitor.config.json berisi "url".
• Jika Anda juga menggunakan Capgo Live Updates, perlu diketahui bahwa server.url config akan menimpa bundle updater; pisahkan kedua workflow tersebut.

Ringkasan

Live reload di Android bisa berjalan dari Windows dan Linux dengan tiga detail ini: bind dev server ke semua interface, pilih alamat yang bisa dijangkau perangkat ("10.0.2.2 untuk emulator, adb reverse untuk USB, IP LAN dengan aturan firewall untuk Wi-Fi), dan jangan masukkan dev config ke release build. Setelah iterasi di Android terasa cepat, web layer yang sama sudah teruji sebelum sampai ke iOS melalui Capgo Build.