> ## 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.

# Sincronizzazione in tempo reale

> App local-first con supporto offline e sincronizzazione automatica in background.

## Come funziona

Le app con sincronizzazione in tempo reale mantengono un database locale sul dispositivo. Le letture sono istantanee (locali), le scritture si accodano localmente e tutto si sincronizza al server in background.

```text theme={"theme":"material-theme-darker"}
Scrittura utente -> Database locale -> Coda upload -> Server -> Postgres
                                                                  |
Lettura utente  <- Database locale <- Replica sincronizzazione <-+
```

Il risultato: letture istantanee, niente spinner di caricamento e un'app che continua a funzionare con connessioni scadenti o offline.

## Cosa configura l'AI

Chiedi all'AI di creare un'app in tempo reale. Riutilizza un database attivo adatto se esiste; altrimenti crea un database, attiva il servizio di sincronizzazione e costruisce un'app in due parti:

* **UI** - app client con database locale, query live e connettore di sincronizzazione
* **Process** - endpoint token, rotta upload sincronizzazione e migration runner

Le credenziali sono archiviate nel [vault](/work/vault). L'AI collega le variabili d'ambiente del database al componente process con lo strumento `db`.

Prima che l'app sia considerata pronta, il database deve mostrare `sync: ready`. Se la sincronizzazione non è pronta, l'app potrebbe renderizzarsi ma i dati in tempo reale tra dispositivi non funzioneranno.

## Regole pratiche

* Scrivi localmente per primo. Lascia che la sincronizzazione carichi in background.
* Mostra stati vuoti, non spinner di caricamento, una volta che i dati locali esistono.
* Mantieni lo stato visibile all'utente in tabelle sincronizzate in modo che sopravviva agli aggiornamenti e all'uso offline.
* Raggruppa le scritture locali correlate insieme in modo che l'UI si aggiorni in un unico passaggio.
* Verifica lo stato di sincronizzazione prima di considerare un'app in tempo reale completata.

## Shell app offline

I template UI possono includere una shell app offline in modo che l'app possa riaprirsi dopo la prima visita senza una rete. La shell app è l'HTML statico, JS, CSS e icone.

* **Shell offline** consente all'app di aprirsi senza una rete
* **Sincronizzazione** mantiene i dati dell'app utilizzabili mentre offline

Insieme: l'app si apre senza una rete, mostra i dati sincronizzati più recenti, accoda le nuove scritture e si sincronizza quando la connessione ritorna.

## Quando usare la sincronizzazione in tempo reale

| Adatto                                          | Eccessivo                     |
| ----------------------------------------------- | ----------------------------- |
| App di gestione attività e note                 | Pagine di marketing statiche  |
| Strumenti collaborativi                         | Invii di moduli una tantum    |
| App da campo con connettività debole            | Siti brochure di sola lettura |
| Qualsiasi cosa che dovrebbe sembrare istantanea | App senza valore offline      |

## Variabili di piattaforma

Kazzle inietta automaticamente un piccolo set di variabili d'ambiente in ogni processo app. Queste sono separate dai tuoi [segreti vault](/work/vault).

| Variabile                         | Cos'è                                               |
| --------------------------------- | --------------------------------------------------- |
| `PORT`                            | La porta su cui il tuo processo deve ascoltare      |
| `HOST`                            | L'hostname a cui associarsi (tipicamente `0.0.0.0`) |
| `KAZZLE_API_URL`                  | URL base utilizzato dagli helper runtime di Kazzle  |
| `KAZZLE_APP_COMPONENT_<NAME>_URL` | URL runtime di un componente sibling                |

### URL sibling

Quando un'app ha più componenti (ad es. un'UI `web` e un processo `server`), Kazzle può iniettare URL per componenti sibling:

```
# Nella parte "web":
KAZZLE_APP_COMPONENT_SERVER_URL=http://localhost:3001

# Nella parte "server":
KAZZLE_APP_COMPONENT_WEB_URL=http://localhost:3000
```

Quando un sibling è già distribuito, il valore iniettato punta a quel componente distribuito. Altrimenti punta all'indirizzo di sviluppo corrente per quel sibling.