Next.js SSR example #1596

balegas · 2024-08-29T21:30:17Z

Items example using SSR.

Load the entire shape on the server and send it down to the client, so that the client gets the initial state of the shape on first response and can resume replication from the tip of the shape stream.

First time with nextjs, I still don't know how some things work. I suppose this is good forn an example. I'm happy to receive feedback from nextjs experts :D

KyleAMathews

Left a few comments.

Don't you want to use either https://nextjs.org/docs/pages/building-your-application/data-fetching/get-server-side-props or https://nextjs.org/docs/pages/building-your-application/data-fetching/get-static-props here? Right now I don't see that any data is being cached during server rendering.

EDIT: Oh I see... this is RSC stuff

examples/nextjs-ssr-example/app/Home.tsx

examples/nextjs-ssr-example/app/shape.tsx

packages/typescript-client/src/client.ts

examples/nextjs-ssr-example/app/page.tsx

netlify · 2024-10-03T00:11:19Z

✅ Deploy Preview for electric-next ready!

Name	Link
🔨 Latest commit	`dc9da79`
🔍 Latest deploy log	https://app.netlify.com/sites/electric-next/deploys/673b23a1b567730008140042
😎 Deploy Preview	https://deploy-preview-1596--electric-next.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify site configuration.

examples/nextjs-ssr-example/app/page.tsx

samwillis · 2024-10-08T12:32:06Z

First, I think there is going to be two ways people want to do SSR with useShape:

Fetch the full snapshot on the server, render it, and then include the snapshot in the HTML sent to the client. This allows the client to just continue from where it was in the stream (just as this PR does). This would make sense for smaller shapes - such as a single issue + comments on a detail view.
Render a subset of the data on the server, not include the snapshot in the HTML sent to the client, and then fetch the full snapshot on the client. This would make sense for larger shapes - such as a very long list of issues, just rendering the "above the fold" on the server. Refetching already rendered data is ok in this situation.

I think we want to provide tooling for both of these cases.

On 1 - snapshot of the shape and resume

While the pattern in this PR works, having to pass the shape snapshot to the component using useShape via props is a little messy. It would be great if we could provide a cleaner API that "just works" with SSR.

I think this is doable if we create a <ShapeSsrStore> (or similar) component that the user wraps their app in. This component will keep track of all useShape calls done during SSR and then inject a <script> tag with the JSON of those shapes as a global (keyed by shapeId?). This can then be read back and used when hydrating the useShapes on the client.

We are somewhat restricted as we cant use a react context, but something like this POC is possible: https://github.com/samwillis/ssr-shape-poc (I've purposely not used any electric, just wanted to test the concept for injection)

By the user adding <ShapeSsrStore>, all useShapes would SSR with automatic resume. (We could make this opt in with a flag to the useShape options)

This is also not tied to Next, and should work with all React SSR frameworks.

On 2 - a minimal subset on the server

I think we should add a getServerSnapshot option to useShape that is only run on the server. The user can configure this to do a direct Postgres query to fore a subset of data for SSR. This would override the shape URL can just any snapshotting from option 1 above.

useShape({
  url: `http://localhost:3000/v1/shape/foo`,
  getServerSnapshot: () => {
    // Do and return a Postgres query
  },
})

thruflo · 2024-10-08T16:44:32Z

Great stuff @samwillis :)

On 2, I wonder if there's a way of supporting order_by and limit of the shape results? An arbitrary query is powerful but means the user needs to format the results in the same way as the shape data. This will become harder as and when we support nested associations. So is there an approach where the user could order/limit/(filter?) the shape when convenient and then drop down to a function when that's not expressive enough?

balegas

@samwillis inspired on your example and Nextjs docs, I gave another try. The idea here is to have a context around the component that takes the server-sent data from props and initializes the shapes on the client --- totally transparent on the client component!

Left some comments

examples/nextjs-ssr-example/app/ssr-shapes-provider.ts

packages/react-hooks/src/react-hooks.tsx

examples/nextjs-ssr-example/app/page.tsx

packages/typescript-client/src/shape.ts

examples/nextjs-ssr-example/app/Home.tsx

balegas · 2024-10-25T15:01:43Z

Render a subset of the data on the server,

@samwillis, @thruflo my initial idea was to call the database directly on the server. This is a powerful pattern to show, but because of the problems with ordering and paging, I thought it would be better to build just on Shapes. The benefit of Shapes is that requests go through the cache and doesn't put load on the server db.

A naive way of rendering the subset of data on the server is to just drop the data that doesn't fit into the initial page rendering :)

balegas · 2024-11-12T14:07:39Z

@samwillis , I did a DX refactoring addressing your concerns with it being simple to specify the shapes across server and client. Have a look at it or ping me to see together.

I also want to replace the base nextjs example with this one (cc @KyleAMathews)

github-actions · 2024-11-18T11:37:32Z

Examples

linearlite: https://linearlite-stage-pr-1596.electric-sql.com
nextjs: https://nextjs-stage-pr-1596.electric-sql.com

thruflo · 2024-11-22T09:08:09Z

.github/workflows/deploy_examples.yml

@@ -62,7 +62,7 @@ jobs:


      - name: Deploy NextJs example
-        working-directory: examples/nextjs-example
+        working-directory: examples/nextjs-ssr-example


Just a naming nit: there's no need to suffix with -example, that's communicated by the parent folder name, so I would suggest examples/nextjs-ssr.

thruflo · 2024-11-22T09:10:05Z

examples/nextjs-ssr-example/README.md

@@ -0,0 +1,22 @@
+# Next.js SSR example


Generally, the README for an example should ideally communicate a bit about what it's trying to show you, i.e.: what is the example, why is it interesting, what can you achieve with the pattern it demonstrates, etc. Plus perhaps some signposts into key parts of the code.

Will work on that when we decide to publish

thruflo · 2024-11-22T09:11:10Z

examples/nextjs-ssr-example/public/logo.svg

We're purple nowadays/

thruflo · 2024-11-22T09:14:49Z

packages/react-hooks/src/react-hooks.tsx

 } from '@electric-sql/client'
 import React from 'react'
 import { useSyncExternalStoreWithSelector } from 'use-sync-external-store/with-selector.js'

 type UnknownShape = Shape<Row<unknown>>
 type UnknownShapeStream = ShapeStream<Row<unknown>>
+export type SerializedShape = {
+  offset: Offset
+  shapeHandle: string | undefined


Another very minor nit but seeings how this is in the react-hooks library not just the example, I've been trying to move us towards just using handle rather than shapeHandle.

Below when you getSerialisedShape you can also just read it from shape.handle rather than shapeStream.shapeHandle.

yep, i started this a while back, things like the offset were not public at the time. Will cleanup.

thruflo · 2024-11-22T09:15:22Z

packages/react-hooks/src/react-hooks.tsx

+  const shape = getShape(shapeStream)
+  return {
+    shapeHandle: shapeStream.shapeHandle,
+    offset: shapeStream.offset,


Does offset work? Is the property not lastOffset?

thruflo · 2024-11-22T09:15:48Z

packages/typescript-client/src/client.ts

@@ -245,6 +245,10 @@ export class ShapeStream<T extends Row<unknown> = Row>
    return this.#shapeHandle
  }

+  get offset() {


I think this is duplicated now -- we already expose lastOffset as a public getter.

gruckion · 2025-01-07T11:43:18Z

I’ve read over the comments on the front page. Not dug into the files changed yet.

I believe this approach should be using hydration and suspense.

https://react.dev/reference/react-dom/client/hydrateRoot

https://react.dev/reference/react/Suspense

An excellent reference / role model would be Tanstack Query. Currently I use it and tRPC.

My current solution using Tanstack Query and tRPC is;

import { DataTableSkeleton } from "@/components/data-table/data-table-skeleton";
import { HydrateClient, tRPCServerApi } from "@/trpc/server";

import { Suspense } from "react";
import { SiteDataTable } from "../components/site-table/site-data-table";

import type { Metadata } from "next";

export const metadata: Metadata = {
  title: "Company Sites",
  description: "Company sites."
};

export default async function CompanySites(props: {
  params: Promise<{ id: string }>;
}) {
  const params = await props.params;
  await tRPCServerApi.site.getAllCompanySites.prefetch({
    companyId: params.id
  });

  return (
    <HydrateClient>
      <Suspense
        fallback={
          <div className="space-y-4 p-2 pt-8">
            <DataTableSkeleton
              columnCount={5}
              searchableColumnCount={1}
              filterableColumnCount={1}
              cellWidths={["12rem", "14rem"]}
              withPagination={true}
              shrinkZero
            />
          </div>
        }
      >
        <SiteDataTable companyId={params.id} />
      </Suspense>
    </HydrateClient>
  );
}

Here you can see this page.tsx allows me to grab the data whilst the page it’s self is requested. The page is sent to the client immediately with the fullback. Once the data is obtained on the server it is streamed to the frontend and gets hydrated.

I also use the new partial pre-rendering. Which works very well in this case. As the initial page and the fallback is stored in a CDN and the page loads instantly. Again, because the request for the page is handled by the server sending back the CDN result and later hydrating the client works seamlessly.

Inside the SiteDataTable, which is a client component, we use the normal useQuery hook. But since we’re using it from within the HydrateClient boundary when the useQuery triggers on the client instead of performing a round trip to the server to fetch the data it instead caches the hydration cache and loads the data from there.

Again because the data was requested at the same time as the page and streamed into the hydration cache the data is already in the client ready to be hydrated.

  const [data] = trpcClient.site.getAllCompanySites.useSuspenseQuery({
    companyId
  });

Then in the client the useQuery call is actually done using useSuspenseQuery. As this will look in the hydration cache. If the prefetch call wasn’t made it will just fetch the data as usual as well.

At the moment I am considering ElectricSQL vs tRPC streaming both use server sent events (SSE) and currently given the above code I already use tRPC offers a nice fit with the existing codebase and a very nice API.

https://trpc.io/docs/server/subscriptions

gruckion

Nice work 👍

gruckion · 2025-01-07T12:11:42Z

examples/nextjs-ssr-example/app/Home.tsx

@@ -0,0 +1,120 @@
+"use client"


In nextJS the file naming conventions are lower kebab case.

https://nextjs.org/docs/app/api-reference/file-conventions

https://x.com/kentcdodds/status/1361536960876085248?s=46

gruckion · 2025-01-07T12:15:51Z

examples/nextjs-ssr-example/app/Home.tsx

@@ -0,0 +1,120 @@
+"use client"
+
+import { v4 as uuidv4 } from "uuid"


Avoid external dependencies. You do not need one for a cryptographically secure uuid anymore.

https://developer.mozilla.org/en-US/docs/Web/API/Crypto/randomUUID

https://x.com/benlesh/status/1857451931427352654?s=46

gruckion · 2025-01-07T12:24:27Z

examples/nextjs-ssr-example/app/Home.tsx

+}
+
+export default function Home() {
+  const { data: items } = useShape(getProxiedOptions(options)) as unknown as {


As unknown as any? Can generics not be used here?

gruckion · 2025-01-07T12:26:28Z

examples/nextjs-ssr-example/app/Home.tsx

+      const itemsMap = new Map()
+      state
+        .concat([{ id: newId, created_at: new Date().getTime() }])
+        .forEach((item) => {


https://biomejs.dev/linter/rules/no-for-each/

gruckion · 2025-01-07T12:27:41Z

examples/nextjs-ssr-example/app/Home.tsx

+          Clear
+        </button>
+      </form>
+      {optimisticItems


Avoid using sort and map directly in the render response. Use a cost above with useMemo.

Also do not use index as the key.

https://react.dev/learn/rendering-lists#why-does-react-need-keys

gruckion · 2025-01-07T12:35:34Z

examples/nextjs-ssr-example/app/layout.tsx

+  description: `Example application with forms and Postgres.`,
+}
+
+export default function RootLayout({


React.PropsWithChildren

gruckion · 2025-01-07T12:37:51Z

examples/nextjs-ssr-example/app/page.tsx

+  table: `items`,
+}
+
+const Page = async () => (


Why is this async? Does the shape can use react hydrate?

gruckion · 2025-01-07T12:38:55Z

examples/nextjs-ssr-example/app/server-shape-provider.tsx

+  children: React.JSX.Element
+  options: SerializedShapeOptions[]
+}) {
+  const clientShapes: SerializedShape[] = []


Use useMemo

gruckion · 2025-01-07T12:40:13Z

examples/nextjs-ssr-example/app/shape-proxy/[...table]/route.ts

@@ -0,0 +1,44 @@
+export async function GET(request: Request) {
+  const url = new URL(request.url)
+  const originUrl = new URL(


Cleaner to just throw if the environment variable is missing or use an escape guard.

gruckion · 2025-01-07T12:42:11Z

examples/nextjs-ssr-example/app/utils.ts

+  // ensure shape is not syncing on the server
+  const serverOptions: Partial<ShapeStreamOptions> = {}
+  if (typeof window === `undefined`) {
+    const controller = new AbortController()


Using fetch and AbortControllers adds a lot of bloat. Maybe use useQuery which has solved this problems already and provides a beautiful API.

Tanstack react query

KyleAMathews reviewed Aug 30, 2024

View reviewed changes

balegas force-pushed the balegas/ssr-example branch from 64f3703 to 2d933e8 Compare October 3, 2024 00:10

balegas commented Oct 3, 2024

View reviewed changes

examples/nextjs-ssr-example/app/page.tsx Outdated Show resolved Hide resolved

balegas commented Oct 3, 2024

View reviewed changes

examples/nextjs-ssr-example/app/page.tsx Outdated Show resolved Hide resolved

balegas force-pushed the balegas/ssr-example branch from 02ffd0d to dd64a75 Compare October 25, 2024 11:59

balegas commented Oct 25, 2024

View reviewed changes

balegas force-pushed the balegas/ssr-example branch from 887f224 to 2d8330e Compare November 9, 2024 00:14

balegas self-assigned this Nov 12, 2024

balegas force-pushed the balegas/ssr-example branch from 0eccfa5 to 1b3880d Compare November 13, 2024 00:04

balegas added 13 commits November 18, 2024 10:12

Next.js SSR example

72f8c24

Some configs

5538326

A few more things after rebase

a485b9a

Hack for adding randomness to fetch requests

ed312ba

Best I was able to do

165820a

Suppress some warning

6b73737

Order items to prevent hydration issues

ec86b0e

Rebase and cleanup

860ec85

Initialise shapes with server data automatically

d6b90cd

updated pnpm

efdc41b

Improved DX

c3a3845

Small cleanup

4890bff

Ready for Cloud

dc9da79

balegas force-pushed the balegas/ssr-example branch from 1b3880d to dc9da79 Compare November 18, 2024 11:23

balegas temporarily deployed to Pull request November 18, 2024 11:23 — with GitHub Actions Inactive

balegas marked this pull request as ready for review November 18, 2024 11:23

deploy ssr example instead of old one

348958a

balegas had a problem deploying to Pull request November 18, 2024 12:37 — with GitHub Actions Failure

balegas had a problem deploying to Pull request November 18, 2024 12:58 — with GitHub Actions Failure

used stage in database name

d11d91d

balegas had a problem deploying to Pull request November 18, 2024 13:51 — with GitHub Actions Failure

balegas had a problem deploying to Pull request November 18, 2024 14:09 — with GitHub Actions Failure

different domain

a999adb

balegas had a problem deploying to Pull request November 18, 2024 15:08 — with GitHub Actions Failure

thruflo reviewed Nov 22, 2024

View reviewed changes

examples/nextjs-ssr-example/public/logo.svg

Copy link

Contributor

thruflo Nov 22, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We're purple nowadays/

balegas reacted with thumbs up emoji

thruflo reviewed Nov 22, 2024

View reviewed changes

gruckion suggested changes Jan 7, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Next.js SSR example #1596

Next.js SSR example #1596

balegas commented Aug 29, 2024 •

edited

Loading

KyleAMathews left a comment •

edited

Loading

netlify bot commented Oct 3, 2024 •

edited

Loading

samwillis commented Oct 8, 2024

thruflo commented Oct 8, 2024

balegas left a comment

balegas commented Oct 25, 2024 •

edited

Loading

balegas commented Nov 12, 2024

github-actions bot commented Nov 18, 2024

thruflo Nov 22, 2024

thruflo Nov 22, 2024

balegas Nov 25, 2024

thruflo Nov 22, 2024

thruflo Nov 22, 2024

balegas Nov 25, 2024

thruflo Nov 22, 2024

thruflo Nov 22, 2024

gruckion commented Jan 7, 2025 •

edited

Loading

gruckion left a comment

gruckion Jan 7, 2025

gruckion Jan 7, 2025

gruckion Jan 7, 2025

gruckion Jan 7, 2025

gruckion Jan 7, 2025

gruckion Jan 7, 2025

gruckion Jan 7, 2025

gruckion Jan 7, 2025

gruckion Jan 7, 2025

gruckion Jan 7, 2025

		@@ -0,0 +1,120 @@
		"use client"

		import { v4 as uuidv4 } from "uuid"

Next.js SSR example #1596

Are you sure you want to change the base?

Next.js SSR example #1596

Conversation

balegas commented Aug 29, 2024 • edited Loading

KyleAMathews left a comment • edited Loading

Choose a reason for hiding this comment

netlify bot commented Oct 3, 2024 • edited Loading

✅ Deploy Preview for electric-next ready!

samwillis commented Oct 8, 2024

On 1 - snapshot of the shape and resume

On 2 - a minimal subset on the server

thruflo commented Oct 8, 2024

balegas left a comment

Choose a reason for hiding this comment

balegas commented Oct 25, 2024 • edited Loading

balegas commented Nov 12, 2024

github-actions bot commented Nov 18, 2024

Examples

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

gruckion commented Jan 7, 2025 • edited Loading

gruckion left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

balegas commented Aug 29, 2024 •

edited

Loading

KyleAMathews left a comment •

edited

Loading

netlify bot commented Oct 3, 2024 •

edited

Loading

balegas commented Oct 25, 2024 •

edited

Loading

gruckion commented Jan 7, 2025 •

edited

Loading