Server-side rendering and bootstrap · Strata Sync

Server-side rendering and bootstrap

Prefetch data on the server, serialize snapshots, and hydrate the client for instant first paint.

Prefetch data on the server, embed it in the HTML, and seed client storage. The client starts its delta stream from where the server left off: no loading spinners.

Why bootstrap matters

Without SSR bootstrap, the browser shows a spinner while fetching from the sync API. With bootstrap, data is embedded in the HTML response: users see content immediately.

Without SSR bootstrap


sequenceDiagram
    participant Browser
    participant Server
    participant SyncAPI

    Browser->>Server: Request page
    Server-->>Browser: HTML (empty shell)
    Browser->>Browser: Mount React, show loading spinner
    Browser->>SyncAPI: Bootstrap request
    SyncAPI-->>Browser: NDJSON stream of model data
    Browser->>Browser: Populate stores, re-render with data

With SSR bootstrap

sequenceDiagram
    participant Browser
    participant Server
    participant SyncAPI

    Server->>SyncAPI: prefetchBootstrap (at request time)
    SyncAPI-->>Server: NDJSON stream
    Server->>Server: Serialize snapshot into page props
    Server-->>Browser: HTML with data embedded
    Browser->>Browser: Seed storage from snapshot
    Browser->>Browser: Create client and start sync
    Browser->>SyncAPI: Delta stream (catch up from lastSyncId)


import {
  prefetchBootstrap,
  serializeBootstrapSnapshot,
} from "@stratasync/next/server";

const snapshot = await prefetchBootstrap({
  endpoint: "https://api.example.com/sync",
  authorization: `Bearer ${userToken}`,
  models: ["Task", "User", "Team"],
  timeout: 10_000,
});


import { seedStorageFromBootstrap } from "@stratasync/next";
import { createIndexedDbStorage } from "@stratasync/storage-idb";

const storage = createIndexedDbStorage({ name: "my-app" });

const result = await seedStorageFromBootstrap({
  storage,
  snapshot: payload,
  dbName: "my-app",
  clearExisting: true,
  closeAfter: true,
});

if (!result.applied) {
  // Schema changed -- need a full re-bootstrap
}


import { isBootstrapSnapshotStale } from "@stratasync/next/server";

const snapshot = await prefetchBootstrap({ endpoint });

if (isBootstrapSnapshotStale(snapshot, 30_000)) {
  // Snapshot is older than 30 seconds -- re-fetch or let the delta stream catch up
}


// app/layout.tsx
import {
  prefetchBootstrap,
  serializeBootstrapSnapshot,
} from "@stratasync/next/server";
import { cookies } from "next/headers";
import { Providers } from "./providers";

export default async function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  const cookieStore = await cookies();
  const token = cookieStore.get("session")?.value;
  let bootstrap = null;

  if (token) {
    try {
      const snapshot = await prefetchBootstrap({
        endpoint: process.env.SYNC_API_URL!,
        authorization: `Bearer ${token}`,
      });
      bootstrap = await serializeBootstrapSnapshot(snapshot, {
        compress: true,
      });
    } catch {
      // Graceful degradation -- client will bootstrap normally
    }
  }

  return (
    <html lang="en">
      <body>
        <Providers bootstrap={bootstrap}>{children}</Providers>
      </body>
    </html>
  );
}


// app/providers.tsx
"use client";

import { useRef, useCallback } from "react";
import { NextSyncProvider, seedStorageFromBootstrap } from "@stratasync/next";
import type { BootstrapSnapshotPayload } from "@stratasync/next/server";
import { createSyncClient } from "@stratasync/client";
import { createIndexedDbStorage } from "@stratasync/storage-idb";
import { createGraphQLTransport } from "@stratasync/transport-graphql";
import { createMobXReactivity } from "@stratasync/mobx";
import { schema } from "../lib/schema";

export function Providers({
  children,
  bootstrap,
}: {
  children: React.ReactNode;
  bootstrap: BootstrapSnapshotPayload | null;
}) {
  const seeded = useRef(false);

  const clientFactory = useCallback(() => {
    const client = createSyncClient({
      schema,
      storage: createIndexedDbStorage({ name: "my-app" }),
      transport: createGraphQLTransport({
        endpoint: "/api/graphql",
        syncEndpoint: "/api/sync",
        wsEndpoint: "wss://api.example.com/sync/ws",
        auth: { getAccessToken: async () => "token" },
      }),
      reactivity: createMobXReactivity(),
    });

    if (bootstrap && !seeded.current) {
      seeded.current = true;
      seedStorageFromBootstrap({
        storage: createIndexedDbStorage({ name: "my-app" }),
        snapshot: bootstrap,
        dbName: "my-app",
        clearExisting: true,
        closeAfter: true,
      });
    }

    return client;
  }, [bootstrap]);

  return (
    <NextSyncProvider client={clientFactory} loading={<p>Loading...</p>}>
      {children}
    </NextSyncProvider>
  );
}


// app/tasks/task-list.tsx
"use client";

import { observer } from "mobx-react-lite";
import { useQuery } from "@stratasync/react";

export const TaskList = observer(function TaskList() {
  const { data: tasks, isLoading } = useQuery("Task", {
    orderBy: (a, b) =>
      (b as Record<string, string>).createdAt.localeCompare(
        (a as Record<string, string>).createdAt
      ),
  });

  if (isLoading) return <p>Loading...</p>;

  return (
    <ul>
      {tasks.map((task) => {
        const t = task as Record<string, string>;
        return (
          <li key={t.id}>
            <strong>{t.title}</strong> {t.status}
          </li>
        );
      })}
    </ul>
  );
});