> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kazzle.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Sinkronisasi realtime

> Aplikasi local-first dengan dukungan offline dan sinkronisasi latar belakang otomatis.

## Cara kerjanya

Aplikasi dengan sinkronisasi realtime menyimpan database lokal di perangkat. Pembacaan bersifat instan (lokal), penulisan antri secara lokal, dan semuanya disinkronkan ke server di latar belakang.

```text theme={"theme":"material-theme-darker"}
User writes -> Local database -> Upload queue -> Server -> Postgres
                                                            |
User reads  <- Local database <- Sync replication <---------+
```

Hasilnya: pembacaan instan, tanpa spinner loading, dan aplikasi yang terus bekerja pada koneksi buruk atau offline.

## Yang AI siapkan

Minta AI untuk membangun aplikasi realtime. AI menggunakan kembali database aktif yang sesuai jika ada; jika tidak, AI membuat database, mengaktifkan layanan sinkronisasi, dan membangun aplikasi dua bagian:

* **UI** - aplikasi klien dengan database lokal, live queries, dan konektor sinkronisasi
* **Process** - token endpoint, rute upload sinkronisasi, dan migration runner

Kredensial disimpan di [vault](/work/vault). AI menghubungkan variabel env database ke komponen proses dengan tool `db`.

Sebelum aplikasi dianggap siap, database harus menampilkan `sync: ready`. Jika sinkronisasi tidak siap, aplikasi mungkin render tetapi data realtime lintas perangkat tidak akan berfungsi.

## Aturan praktis

* Tulis secara lokal terlebih dahulu. Biarkan sinkronisasi mengunggah di latar belakang.
* Tampilkan empty states, bukan loading spinners, setelah data lokal ada.
* Simpan state yang terlihat pengguna di tabel yang disinkronkan sehingga bertahan melalui refresh dan penggunaan offline.
* Kelompokkan penulisan lokal terkait bersama-sama sehingga UI diperbarui sebagai satu langkah.
* Verifikasi kesehatan sinkronisasi sebelum menganggap aplikasi realtime selesai.

## Shell aplikasi offline

Template UI dapat menyertakan shell aplikasi offline sehingga aplikasi dapat dibuka kembali setelah kunjungan pertama tanpa jaringan. Shell aplikasi adalah HTML, JS, CSS, dan ikon statis.

* **Shell offline** membuat aplikasi terbuka tanpa jaringan
* **Sync** menjaga data aplikasi tetap dapat digunakan saat offline

Bersama-sama: aplikasi terbuka tanpa jaringan, menampilkan data sinkronisasi terbaru, antri penulisan baru, dan sinkronisasi saat koneksi kembali.

## Kapan menggunakan sinkronisasi realtime

| Cocok                                       | Berlebihan                       |
| ------------------------------------------- | -------------------------------- |
| Aplikasi task manager dan notes             | Halaman pemasaran statis         |
| Alat kolaboratif                            | Pengiriman formulir sekali jalan |
| Aplikasi lapangan dengan konektivitas lemah | Situs brosur read-only           |
| Apa pun yang harus terasa instan            | Aplikasi tanpa nilai offline     |

## Variabel platform

Kazzle menyuntikkan serangkaian kecil variabel lingkungan ke setiap proses aplikasi secara otomatis. Ini terpisah dari [vault secrets](/work/vault) Anda sendiri.

| Variabel                          | Apa itu                                             |
| --------------------------------- | --------------------------------------------------- |
| `PORT`                            | Port yang harus didengarkan proses Anda             |
| `HOST`                            | Hostname untuk bind (biasanya `0.0.0.0`)            |
| `KAZZLE_API_URL`                  | URL dasar yang digunakan oleh helper runtime Kazzle |
| `KAZZLE_APP_COMPONENT_<NAME>_URL` | URL runtime komponen sibling                        |

### URL sibling

Ketika aplikasi memiliki beberapa komponen (misalnya UI `web` dan proses `server`), Kazzle dapat menyuntikkan URL untuk komponen sibling:

```
# Di bagian "web":
KAZZLE_APP_COMPONENT_SERVER_URL=http://localhost:3001

# Di bagian "server":
KAZZLE_APP_COMPONENT_WEB_URL=http://localhost:3000
```

Ketika sibling sudah di-deploy, nilai yang disuntikkan menunjuk ke komponen yang di-deploy tersebut. Jika tidak, nilai tersebut menunjuk ke alamat pengembangan saat ini untuk sibling tersebut.