Server rendering

Server rendering and offline replication solve different problems. The server can produce an authorized first response; the browser still restores and synchronizes its persistent database replica after hydration.

Choose what the server owns

Use server queries for metadata, route decisions, public content, and an authorized first paint when that latency matters. Use the browser client for persistent offline data, live local queries, optimistic operations, receipts, and multi-tab coordination.

Do not create a browser Db handle in a Server Component. It depends on browser storage and session coordination.

Query with the request principal

Ramose does not currently export a server database client or a ramose.open function. Use the MCP protocol for supported server queries, with the request’s verified authorization. Render the resulting plain data through your application framework.

Keep personalized results scoped to the principal and request. Do not put them in a shared framework cache without authorization-aware keys.

Hydrate presentation, not storage

Pass plain initial rows to the client for immediate presentation if your adapter supports seeding that exact query. The browser then opens its database, restores local state, and validates/catches up through normal synchronization.

An HTML payload is not a trusted database snapshot. It has no durable cursor, outbox, policy transition state, or multi-tab ownership. Do not write arbitrary server props directly into IndexedDB as if they came from the synchronization protocol.

Reconcile visibly

The client result may be newer than SSR because another device committed after render. It may also be locally optimistic because this browser has queued work. Let the browser query become authoritative for interaction as soon as it is ready.

If the client reports stale, keep the complete result visible and add connectivity context. Avoid an SSR-to-spinner flash by retaining the initial presentation until the first local query snapshot is ready.

Protect principal changes

Key the browser client by stable principal/session generation. On sign-out or account switch, close the old client and mount a new one. Never reuse one principal’s database handles, query snapshots, or queued receipts for another principal.

Static generation

Use static generation only for truly public, catalog-independent content. Personalized data should be rendered at request time or loaded by the browser. Revalidation cannot represent arbitrary policy changes safely without an authorization-aware cache design.