> ## Documentation Index
> Fetch the complete documentation index at: https://sonamu.cartanova.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Data Preloading
> Preload data on server with registerSSR
Learn how to preload data on the server and pass it to the client using Sonamu's `registerSSR`.
## Data Preloading Overview
Per-route preload config Direct backend call
Type-safe queries Model/method specification
Auto inject to QueryClient Hydration handling
No network overhead Fast response
## How to Use registerSSR
### Basic Structure
```typescript theme={null}
// api/src/application/sonamu.ts
import { registerSSR } from "sonamu";
registerSSR({
path: "/users/:id",
preload: (params) => [
{
modelName: "UserModel",
methodName: "getUser",
params: ["C", parseInt(params.id)],
serviceKey: ["User", "getUser"],
},
],
});
```
**Process**:
1. Server receives request for `/users/123`
2. `path` matching: `/users/:id` → `params = { id: "123" }`
3. Execute `preload` function → returns `SSRQuery[]`
4. Direct backend call to `UserModel.getUser("C", 123)` (no HTTP!)
5. Inject result with `QueryClient.setQueryData(["User", "getUser", "C", 123], result)`
6. Send HTML + dehydratedState to client
7. Client hydrates and immediately uses data
### SSRQuery Type
```typescript theme={null}
type SSRQuery = {
modelName: string; // "UserModel" - Backend model class name
methodName: string; // "getUser" - Model method name
params: unknown[]; // ["C", 123] - Method parameters (excluding Context)
serviceKey: [string, string]; // ["User", "getUser"] - React Query queryKey prefix
};
```
**Important**: `params` follows the **backend method's parameter order** (excluding Context).
## Practical Examples
### Single Data Loading
Preload user information on user detail page.
```typescript theme={null}
// api/src/application/sonamu.ts
registerSSR({
path: "/users/:id",
preload: (params) => [
{
modelName: "UserModel",
methodName: "getUser",
params: ["C", parseInt(params.id)], // subset, id order
serviceKey: ["User", "getUser"],
},
],
});
```
```typescript theme={null}
// web/src/routes/users/$id.tsx
import { createFileRoute } from "@tanstack/react-router";
import { UserService } from "@/services/services.generated";
export const Route = createFileRoute("/users/$id")({
component: UserPage,
});
function UserPage() {
const { id } = Route.useParams();
// Automatically uses data preloaded from server
// isLoading: false (data already exists)
const { data } = UserService.useUser("C", parseInt(id));
return (
{data?.user.username}
{data?.user.email}
Bio: {data?.user.bio}
);
}
```
### Multiple Data Simultaneous Loading
Preload both post and comments on post detail page.
```typescript theme={null}
// api/src/application/sonamu.ts
registerSSR({
path: "/posts/:id",
preload: (params) => [
// Post data
{
modelName: "PostModel",
methodName: "getPost",
params: ["C", parseInt(params.id)],
serviceKey: ["Post", "getPost"],
},
// Comment list
{
modelName: "CommentModel",
methodName: "getCommentsByPost",
params: [parseInt(params.id)],
serviceKey: ["Comment", "getCommentsByPost"],
},
],
});
```
```typescript theme={null}
// web/src/routes/posts/$id.tsx
import { createFileRoute } from "@tanstack/react-router";
import { PostService, CommentService } from "@/services/services.generated";
export const Route = createFileRoute("/posts/$id")({
component: PostPage,
});
function PostPage() {
const { id } = Route.useParams();
// Both data are preloaded
const { data: post } = PostService.usePost("C", parseInt(id));
const { data: comments } = CommentService.useCommentsByPost(parseInt(id));
return (
{post?.post.title}
{post?.post.content}
Comments ({comments?.comments.length})
{comments?.comments.map((comment) => (
{comment.content}
))}
);
}
```
### Parameter Processing
You can process URL parameters before use.
```typescript theme={null}
// api/src/application/sonamu.ts
registerSSR({
path: "/categories/:slug/posts",
preload: (params) => {
// Logic to convert slug to id
const categoryId = getCategoryIdBySlug(params.slug);
return [
{
modelName: "CategoryModel",
methodName: "getCategory",
params: [categoryId],
serviceKey: ["Category", "getCategory"],
},
{
modelName: "PostModel",
methodName: "getPostsByCategory",
params: [categoryId, { page: 1, pageSize: 20 }],
serviceKey: ["Post", "getPostsByCategory"],
},
];
},
});
```
### Conditional Preloading
Load different data based on conditions.
```typescript theme={null}
// api/src/application/sonamu.ts
registerSSR({
path: "/dashboard/:tab",
preload: (params) => {
const queries: SSRQuery[] = [
// Common data: User info
{
modelName: "UserModel",
methodName: "getCurrentUser",
params: [],
serviceKey: ["User", "getCurrentUser"],
},
];
// Load additional data based on tab
if (params.tab === "posts") {
queries.push({
modelName: "PostModel",
methodName: "getMyPosts",
params: [{ page: 1, pageSize: 20 }],
serviceKey: ["Post", "getMyPosts"],
});
} else if (params.tab === "settings") {
queries.push({
modelName: "SettingsModel",
methodName: "getUserSettings",
params: [],
serviceKey: ["Settings", "getUserSettings"],
});
}
return queries;
},
});
```
## Query Key Matching
For preloaded data to match the client's useQuery, **queryKey must match exactly**.
### Correct Matching
```typescript theme={null}
// Server: registerSSR
{
modelName: "UserModel",
methodName: "getUser",
params: ["C", 123],
serviceKey: ["User", "getUser"], // Stored as ["User", "getUser", "C", 123]
}
// Client: useQuery
UserService.useUser("C", 123); // queryKey: ["User", "getUser", "C", 123]
// ✅ Match successful!
```
### Incorrect Matching
```typescript theme={null}
// Server: Preloaded with Subset "C"
{
params: ["C", 123],
serviceKey: ["User", "getUser"],
}
// Client: Requesting Subset "A"
UserService.useUser("A", 123); // queryKey: ["User", "getUser", "A", 123]
// ❌ Match failed - Client makes new API call
```
## SSRRoute Options
### disableHydrate
Disable Hydration and render new on client.
```typescript theme={null}
registerSSR({
path: "/admin/report",
preload: (params) => [
/* ... */
],
disableHydrate: true, // Disable Hydration
});
```
**Use cases**:
* When server/client rendering results may differ
* When real-time data is important
* Resolving Hydration mismatch
### cacheControl
Set Cache-Control header for SSR response.
```typescript theme={null}
registerSSR({
path: "/posts/:id",
preload: (params) => [
/* ... */
],
cacheControl: {
maxAge: 3600, // 1 hour cache
sMaxAge: 7200, // 2 hour CDN cache
staleWhileRevalidate: 86400, // Serve stale content for 1 day
},
});
```
## Internal Operation Principle
### 1. Server Rendering Process
```typescript theme={null}
// sonamu/src/ssr/renderer.ts (simplified)
export async function renderSSR(url: string, route: SSRRoute, params: Record) {
// 1. Execute preload
const preloadConfig = route.preload ? route.preload(params) : [];
const preloadedData: PreloadedData[] = [];
// 2. Execute each SSRQuery
for (const { modelName, methodName, params: apiParams, serviceKey } of preloadConfig) {
const api = Sonamu.syncer.apis.find(
(a) => a.modelName === modelName && a.methodName === methodName,
);
// 3. Direct backend API call (no HTTP!)
const result = await Sonamu.invokeApiForSSR(api, apiParams);
// 4. Save PreloadedData
preloadedData.push({
queryKey: [...serviceKey, ...apiParams],
data: result,
});
}
// 5. Call entry-server.generated.tsx's render()
const { html, dehydratedState } = await render(url, preloadedData);
// 6. Inject data into HTML
const ssrDataScript = ``;
return html.replace(" ", `${ssrDataScript}\n`);
}
```
### 2. Data Injection in entry-server
```typescript theme={null}
// entry-server.generated.tsx
export async function render(url: string, preloadedData: PreloadedData[] = []) {
const queryClient = new QueryClient();
// Inject PreloadedData into QueryClient
for (const { queryKey, data } of preloadedData) {
queryClient.setQueryData(queryKey, data);
}
// Dehydrate (serialize)
const dehydratedState = dehydrate(queryClient);
// React rendering
const appHtml = renderToString(