Server-Side Rendering

Server-side rendering (SSR) renders your React application to HTML on the server, sends that HTML to the browser, and then hydrates it on the client. This improves first-paint performance and lets crawlers see fully rendered markup. SSR in Modelence is opt-in. Existing client-only apps keep working unchanged — you only get SSR after you explicitly enable it.

Enabling SSR

Set ssr: true in startApp:

src/server/app.ts

import { startApp } from 'modelence/server';
import todoModule from './todo';

startApp({
  modules: [todoModule],
  ssr: true,
});

That’s the only required change. The Modelence build always emits SSR artifacts, so there is no separate build flag — startApp({ ssr: true }) decides whether they are used at runtime.

When ssr is omitted or false, Modelence renders on the client only, exactly as before. Nothing about your existing app changes until you opt in.

Routing with SSR

For the server and client to resolve the same route, a location-driven router must be told which URL to render. Pass a router function to renderApp. Modelence calls it with the current location on the server and again on the client during hydration, so both produce the same tree:

src/client/index.tsx

import { renderApp } from 'modelence/client';
import { StaticRouter } from 'react-router-dom/server';
import { BrowserRouter } from 'react-router-dom';
import routes from './routes';

renderApp({
  loadingElement: <div>Loading…</div>,
  routesElement: routes,
  router: ({ children, location }) =>
    typeof window === 'undefined'
      ? <StaticRouter location={location ?? '/'}>{children}</StaticRouter>
      : <BrowserRouter>{children}</BrowserRouter>,
});

The location passed to the router is path + search (the hash is never sent to the server), matching what the browser sees on hydration. This avoids hydration mismatches.

Without a router, a location-driven router (like React Router) will render its default route on the server and a different route on the client, producing a hydration mismatch. Only pass router when your routing depends on the current URL.

Data fetching and hydration

Session is rendered on the server and hydrated on the client, so useSession() returns the correct value on the very first render with no flash of logged-out UI.
Queries (modelenceQuery) run on the server and their results are serialized into the HTML, so cached data is available immediately after hydration.
Live queries (modelenceLiveQuery) are WebSocket subscriptions with no server snapshot — they stay pending during SSR and connect after hydration on the client.

See Queries and Live Queries for how to call methods from the client.

Get Started

Core Concepts

Features

Tutorials

Server-Side Rendering

Enabling SSR

Routing with SSR

Data fetching and hydration

​Enabling SSR

​Routing with SSR

​Data fetching and hydration

​Related

Enabling SSR

Routing with SSR

Data fetching and hydration

Related