SSR #1905

drew-harris · 2025-10-31T19:54:52Z

The PR adds a utility function exported from core, that allows the user to sync auth state to a cookie that a server can read.

It also creates a Framework class in core that makes http requests to get triples and keeps a cache of results. It's designed to be framework agnostic, if we want to add ssr to other frameworks, other cool things.

I created a new init function / suspense provider under a /nextjs import in the react package.

Important

I renamed a backend route from /runtime/query to /runtime/framework/query to make it more clear that the route is meant to only be used with the FrameworkClient class. It also changes so that if an incorrect refresh token is used, it will ignore the refresh token all together and query anonymously.

Example Repo Readme:

Version to try: 0.22.92-experimental.drewh-ssr.20348370870.1

InstantDB Next.JS SSR Example

This repo demonstrates NextJS SSR and cookie sync. Built on top of create-instant-app's NextJS todo example.

Setup Cookie Sync (Optional)

Create a file at src/app/api/instant/route.ts like so:

import { createInstantRouteHandler } from "@instantdb/react/nextjs";

export const { POST } = createInstantRouteHandler({
  appId: process.env.NEXT_PUBLIC_INSTANT_APP_ID!,
});

Add the endpoint to your database config in src/lib/db.ts

import { init } from "@instantdb/react/nextjs";
import schema from "../instant.schema";

export const db = init({
  appId: process.env.NEXT_PUBLIC_INSTANT_APP_ID!,
  firstPartyPath: "/api/instant",
  schema,
  useDateObjects: true,
});

Setup SSR

Create an InstantProvider

"use client"

import { InstantSuspenseProvider } from "@instantdb/react/nextjs";
import { type User } from "@instantdb/react";
import { db } from "@/lib/db"

export default function InstantProvider({
  children,
  user,
}: {
  children: React.ReactNode;
  user: User;
}) {
  return (
    <InstantSuspenseProvider user={user} db={db}>
      {children}
    </InstantSuspenseProvider>
  );
}```

### Use InstantProvider in `layout` 

// src/app/layout.tsx 

```typescript
import InstantProvider from "./InstantProvider";
import { getUserOnServer } from "@instantdb/react/nextjs";

export default async function RootLayout({
  children,
}: Readonly<{
  children: React.ReactNode;
}>) {
  const user = await getUserOnServer(process.env.NEXT_PUBLIC_INSTANT_APP_ID!);
  return (
    <html lang="en">
      <body className="antialiased">
        <InstantProvider user={user}>{children}</InstantProvider>
      </body>
    </html>
  );
}

Using SSR

Instead of using db.useQuery you can use db.useSuspenseQuery instead.

If a page is rendering on the server, the server will make an HTTP request to Instant to retrieve the results before rendering.

If the page is running on the client, it will re-use the existing webhook connection.

SSR and Auth

The db.useAuth function works as normal, except that if you provide the user object to InstantSuspenseProvider higher in the component tree, it will skip a loading state.

This also works with <db.SignedIn> and <db.SignedOut> allowing you to skip any flashes of loading spinners or blank pages.

client/sandbox/react-nextjs/tsconfig.json

github-actions · 2025-10-31T19:59:09Z

View Vercel preview at instant-www-js-drewh-ssr-jsv.vercel.app.

client/packages/core/src/createRouteHandler.ts

client/packages/core/src/Reactor.js

client/sandbox/react-nextjs/config.ts

client/www/pages/docs/backend.md

stopachka

Great work @drew-harris !

client/packages/core/__tests__/src/serializeSchema.test.ts

client/packages/core/src/Reactor.js

client/packages/core/src/createRouteHandler.ts

client/packages/core/src/framework.ts

client/sandbox/react-nextjs/app/play/ssr/db.ts

client/www/pages/docs/backend.md

stopachka

This is looking good to me!

client/packages/core/src/Reactor.js

fixes after new peristed objects format classname order - prettier add copy buttons to docs fix build issues after rebase fix more build issues after rebase fix infinite recurse with useauth via ssr

stopachka

Ship it sir!!!

client/packages/core/src/Reactor.js

client/packages/core/src/createRouteHandler.ts

client/packages/core/src/framework.ts

client/packages/react/src/next-ssr/HydrationStreamProvider.tsx

client/packages/react/src/next-ssr/getUserFromInstantCookie.ts

client/www/pages/docs/backend.md

drew-harris commented Oct 31, 2025

View reviewed changes

client/sandbox/react-nextjs/tsconfig.json Outdated Show resolved Hide resolved

drew-harris force-pushed the drewh/ssr branch from 8e4e9fd to cf80308 Compare October 31, 2025 19:57