From 97084a38dede673d5acb03b9ca6ea4f1c939fdc4 Mon Sep 17 00:00:00 2001
From: Tom Ballinger <tom@convex.dev>
Date: Thu, 6 Feb 2025 11:00:11 -0800
Subject: [PATCH] Document initialData

---
 README.md | 41 +++++++++++++++++++++++++++++++++++++++++
 1 file changed, 41 insertions(+)

diff --git a/README.md b/README.md
index 9cfb18b..d65c280 100644
--- a/README.md
+++ b/README.md
@@ -87,6 +87,47 @@ Running a mutation looks like
 </form>
 ```
 
+### Server-side rendering
+
+`useQuery()` accepts an `initialData` option in its third argument.
+By defining a `load()` function in a +page.server.ts file
+that uses the `ConvexHttpClient` to request the same query to get initial data
+and passing that through to the `initialData` option of a useQuery call you can avoid an initial loading state.
+
+```ts
+// +page.server.ts
+import { ConvexHttpClient } from 'convex/browser';
+import type { PageServerLoad } from './$types.js';
+import { PUBLIC_CONVEX_URL } from '$env/static/public';
+import { api } from '../convex/_generated/api.js';
+
+export const load = (async () => {
+	const client = new ConvexHttpClient(PUBLIC_CONVEX_URL!);
+	return {
+		messages: await client.query(api.messages.list, { muteWords: [] })
+	};
+}) satisfies PageServerLoad;
+```
+
+```svelte
+<script lang="ts">
+	// +page.svelte
+	import type { PageData } from './$types.js';
+	let { data }: { data: PageData } = $props();
+
+	import { useQuery, useConvexClient } from '$lib/client.svelte.js';
+	import { api } from '../convex/_generated/api.js';
+
+	const messages = useQuery(
+		api.messages.list,
+		() => args,
+		() => ({ initialData: data.messages })
+	);
+</script>
+```
+
+Combining specifying `initialData` and either setting the `keepPreviousData` option to true or never modifying the arguments passed to a query should be enough to avoid ever seeing a loading state for a `useQuery()`.
+
 ### Deploying a Svelte App
 
 In production build pipelines use the build command