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

# リアルタイム同期

> オフラインサポートと自動バックグラウンド同期を備えたローカルファースト アプリ。

## 仕組み

リアルタイム同期を備えたアプリは、デバイス上にローカルデータベースを保持します。読み取りは即座（ローカル）、書き込みはローカルでキューイングされ、すべてがバックグラウンドでサーバーに同期されます。

```text theme={"theme":"material-theme-darker"}
ユーザー書き込み -> ローカルデータベース -> アップロードキュー -> サーバー -> Postgres
                                                            |
ユーザー読み取り  <- ローカルデータベース <- 同期レプリケーション <---------+
```

結果：即座の読み取り、ローディングスピナーなし、悪い接続やオフラインでも動作し続けるアプリ。

## AI が設定すること

AI にリアルタイムアプリを構築するよう依頼します。適切なアクティブなデータベースが存在する場合は再利用し、そうでない場合はデータベースを作成し、同期サービスを有効にして、2 部構成のアプリを構築します：

* **UI** - ローカルデータベース、ライブクエリ、同期コネクタを備えたクライアントアプリ
* **Process** - トークンエンドポイント、同期アップロードルート、マイグレーションランナー

認証情報は[Vault](/work/vault)に保存されます。AI は `db` ツールを使用してデータベース環境変数をプロセスコンポーネントに接続します。

アプリが準備完了と見なされる前に、データベースは `sync: ready` を表示する必要があります。同期が準備完了でない場合、アプリはレンダリングされる可能性がありますが、クロスデバイスのリアルタイムデータは機能しません。

## 経験則

* ローカルに最初に書き込みます。バックグラウンドで同期アップロードを行わせます。
* ローカルデータが存在したら、ローディングスピナーではなく空の状態を表示します。
* ユーザーに見える状態を同期テーブルに保持して、更新とオフライン使用に対応させます。
* 関連するローカル書き込みをグループ化して、UI が 1 ステップで更新されるようにします。
* リアルタイムアプリを完成させる前に同期の健全性を確認します。

## オフラインアプリシェル

UI テンプレートにはオフラインアプリシェルを含めることができるため、最初の訪問後にネットワークなしでアプリを再度開くことができます。アプリシェルは静的 HTML、JS、CSS、アイコンです。

* **オフラインシェル**はネットワークなしでアプリを開きます
* **同期**はオフライン中にアプリデータを使用可能に保ちます

合わせて：アプリはネットワークなしで開き、最新の同期データを表示し、新しい書き込みをキューイングし、接続が戻ったときに同期します。

## リアルタイム同期を使用する場合

| 適している            | 過剰              |
| ---------------- | --------------- |
| タスクマネージャーとノートアプリ | 静的マーケティングページ    |
| コラボレーションツール      | 1 回限りのフォーム送信    |
| 接続が弱いフィールドアプリ    | 読み取り専用パンフレットサイト |
| 即座に感じるべきもの       | オフラインの価値がないアプリ  |

## プラットフォーム変数

Kazzle はすべてのアプリプロセスに自動的に小さな環境変数セットを注入します。これらは独自の[Vault シークレット](/work/vault)とは別です。

| 変数                                | 説明                           |
| --------------------------------- | ---------------------------- |
| `PORT`                            | プロセスがリッスンするポート               |
| `HOST`                            | バインドするホスト名（通常は `0.0.0.0`）    |
| `KAZZLE_API_URL`                  | Kazzle ランタイムヘルパーが使用するベース URL |
| `KAZZLE_APP_COMPONENT_<NAME>_URL` | 兄弟コンポーネントのランタイム URL          |

### 兄弟 URL

アプリに複数のコンポーネント（例：`web` UI と `server` プロセス）がある場合、Kazzle は兄弟コンポーネントの URL を注入できます：

```
# "web" パートで：
KAZZLE_APP_COMPONENT_SERVER_URL=http://localhost:3001

# "server" パートで：
KAZZLE_APP_COMPONENT_WEB_URL=http://localhost:3000
```

兄弟がすでにデプロイされている場合、注入された値はそのデプロイされたコンポーネントを指します。そうでない場合は、その兄弟の現在の開発アドレスを指します。