ssr

[clever steppe]

how can I use convex for ssr?

[grim mauve]

Hi @clever steppe. I'm kapa.ai, your friendly support bot. I will try to answer your question by searching through the knowledge base. :wave:

---

To use Convex for SSR (Server-Side Rendering), the approach depends on the framework you are using. Here are the main options based on the knowledge sources:

---

TanStack Start

• Recommended Approach: Use useSuspenseQuery() from TanStack Query with Convex. This enables live-updating queries on the client and server-rendered data on the server.
• How it works: On the server, Convex fetches query results ad-hoc (not via a WebSocket), and TanStack Start ensures all queries use a consistent logical timestamp to avoid data inconsistencies.
• Example:

  const { data } = useSuspenseQuery(convexQuery(api.messages.list, {}));
  

• Loaders: You can use route loaders to preload data for SSR and fast client-side navigation.

  export const Route = createFileRoute('/posts')({
    loader: async (opts) => {
      await opts.context.queryClient.ensureQueryData(
        convexQuery(api.messages.list, {}),
      );
    },
    component: () => {
      const { data } = useSuspenseQuery(convexQuery(api.messages.list, {}));
      // render data...
    },
  });
  

  Convex TanStack Start SSR Guide

---

Next.js

• Client Components: For fully reactive data, use Convex in Client Components. The Convex client maintains a live connection to your deployment and updates as data changes.
• Server Components: You can fetch Convex data in Server Components using the fetchQuery function from convex/nextjs. Note that this data is non-reactive (static at render time).

  import { fetchQuery } from "convex/nextjs";
  import { api } from "@/convex/_generated/api";

export async function StaticTasks() {
const tasks = await fetchQuery(api.tasks.list, { list: "default" });
// render tasks...
return <div>...</div>;
}

[Next.js Server Rendering with Convex](<https://docs.convex.dev/client/react/nextjs/server-rendering#using-convex-to-render-server-components>)

- **Server Actions and Route Handlers:** You can also use `fetchQuery`, `fetchMutation`, and `fetchAction` in Next.js Server Actions and Route Handlers.
```tsx
import { fetchMutation, fetchQuery } from "convex/nextjs";
// ...use in server actions or API routes

Next.js Server Actions and Route Handlers

• Authentication: For authenticated SSR, you need to pass the authentication token to Convex when fetching data server-side. This is typically done by passing the token as an argument to fetchQuery or similar functions. More details are in the Next.js pages router docs: SSR with Auth

---

Stability

Convex SSR support is considered stable for both TanStack Start and Next.js, though some APIs are marked as beta as the team continues to improve the developer experience. The current APIs are not expected to be removed, and production usage is supported. How stable is SSR?

---

If you have a specific framework or use case in mind, let me know and I can provide more targeted guidance!

Note: you can ask me a follow up question by @ mentioning me again :speech_balloon:

@clever steppe Kapa.ai is still learning and improving, please let me know how I did by reacting below.

[clever steppe]

@grim mauve what about svelte kit?

[grim mauve]

Let me check the knowledge base for you again. One moment! :books:

---

For SvelteKit, you can use Convex for querying data and building reactive apps, but SSR (Server-Side Rendering) with Convex is not as fully documented or officially supported as it is for React frameworks like Next.js or TanStack Start.

The official Svelte Quickstart shows how to set up Convex in a SvelteKit app and use the convex-svelte package for client-side reactivity. However, there is no explicit documentation or example for SSR with Convex in SvelteKit in the current knowledge sources.

Community discussions confirm that Convex works well with Svelte for client-side data, but Convex Auth and SSR are not fully supported or documented yet. Some users have experimented with workarounds, such as using Clerk for authentication and manually setting tokens, but there are unresolved issues (e.g., ctx.auth.getUserIdentity() returning null during SSR) and no official guidance for SSR workflows in SvelteKit at this time. Trusted support staff have also stated that Svelte support for Convex Auth and SSR "is not supported atm, and it might be a while before we get to Svelte" Quickstart Svelte Discord: SvelteKit Auth.

Summary:

• You can use Convex in SvelteKit for client-side data fetching and reactivity.
• There is no official or fully documented SSR support for Convex in SvelteKit yet.
• For SSR or authenticated SSR, you may encounter limitations or need to implement custom workarounds, but these are not officially supported or documented.

If SSR with Convex is a critical requirement for your SvelteKit project, you may want to monitor Convex updates or consider using a React-based framework for now.

Note: you can ask me a follow up question by @ mentioning me again :speech_balloon: