How to create a full-stack NextJS 14 app with URQL's executeExchange

[gregbrowndev]

Context

Hi,

Just for fun/learning, I'm building a full-stack, monolithic NextJS app using GraphQL-Yoga and URQL. The Yoga server can be embedded into a NextJS API, which allows for client-side rendering with URQL configured with the fetchExchange. However, I'm having difficulty configuring URQL for the server environment.

To perform server-side rendering and ensure all GraphQl requests are handled in-memory, we can replace the fetchExchange with an executeExchange when creating the URQL Client. This exchange receives the executable schema on the server directly and allows Graphql queries to be routed to the resolvers in-memory.

The project source can be found here: https://github.com/gregbrowndev/todo-app/

Problem

The problem I'm running into, for several reasons below, is that creating this exchange requires async/await, which seems to not be the intended situation compared to all the other exchanges. This makes it very difficult to initialise the Client and UrqlProvider in the root layout without being forced to use useEffect/useState, suspense or otherwise conditionally render the entire component tree while the promise is resolved. This effectively makes SSR useless, as the loading UI is always rendered even though the promise resolves very quickly. This could be solved by configuring every page of the app to use streaming-SSR. However, a better solution would be have immediate, synchronous initialisation in the browser environment and to simply block rendering on the server until the client is ready to use (a slight increased latency to avoid content flashing/streaming on the screen is better IMO).

The file below is in my NextJS project, src/lib/server.ts. This creates the executor exchange and the Yoga server (left in for context). Both depend on the executable schema, which is actually in a separate yarn workspace, e.g. @repo/server:

"use server"
import {executeExchange} from "@urql/exchange-execute";
import {createYoga} from "graphql-yoga";
import { type Context} from "@repo/server/graphql";
import { type Exchange} from "urql";

// Note: executable schema imported from @repo/server

/** Create a local executor
 *   Returns a URQL exchange for the GraphQL client to use when
 *   server-side rendering. This allows the NextJS server to resolve
 *   graphql queries while rendering without making additional network
 *   requests.
 */
export async function createLocalExecutor(): Promise<Exchange> {
    const { schema } = await import("@repo/server/graphql");
    return executeExchange({
        schema,
        context: () => makeContext()
    })
}

/** Create a GraphQL Yoga server
 *   Returns a server that can be embedded into a NextJS route, so it
 *   can serve graphql requests to the client when client-side rendering.
 */
export async function createHttpExecutor(): Promise<ReturnType<typeof createYoga>> {
    const { schema } = await import("@repo/server/graphql");
    return createYoga<any, Context>({
        schema,
        graphqlEndpoint: "/api/graphql",
        fetchAPI: { Response },
        context: () => makeContext()
    })
}

async function makeContext(): Promise<Context> {
    // Load environment variables, create DB connection/session, etc.
    return {
        timeNow: new Date()
    };
}

From above, you can see several reasons why the exchange becomes async (not all might be necessary):

• The schema is dynamically imported, e.g. const { schema } = await import("@repo/server/graphql");. This is an attempt to prevent the server-side code leaking into the client-side bundle. The import returns a Promise.
• The functions are marked as server actions with use server. Again, this is to stop the server code leaking into the client bundle. This has proved effective since my @repo/server project uses Node APIs, such as fs.readFileSync to read in the graphql.schema files, and without wrapping this file in use server, NextJS would completely break. However, in order to make this file "server only", all exported functions (server actions) must be async.
• Create request context for the server. In order to create the execute exchange, we need to create the context for every operation. This means initialising the server to handle the request, e.g. reading env vars, creating a DB session, etc. Some of this should be done once per server start (a separate challenge in NextJS), but some parts should be once-per-request.

Even if there is a smart solution to solve the bundling problem, I think creating the context for each request will in general require async.

Observation: the context arg in the execute exchange accepts a ((operation: Operation) => any) | any. Not really sure yet if that's going to be a problem, or if the context can be created at the same time as the exchange (once per SSR hopefully).

Additional comments

So I hope you can see my issue. My current attempt at solving this is to create a separate Layout/Provider for each environment. We eliminate the conditional rendering (at least the loading state), since the Client for the server environment can be initialised in an async server component, while for the browser environment, we can initialise the client synchronously to begin with.

The problem now seems to be NextJS/URQL is not happy at all that the content does not "match" between the SSR and CSR.

• src/contexts/graphql/provider.tsx

  "use client";
  
  import React from "react";
  import {GraphqlClientProvider} from "@/contexts/graphql/provider-client.tsx";
  import {GraphqlServerProvider} from "@/contexts/graphql/provider-server.tsx";
  
  export function GraphqlProvider({ children }: React.PropsWithChildren) {
      const isClient = typeof window !== "undefined";
      const Provider = isClient ? GraphqlClientProvider : GraphqlServerProvider;
  
      return (
          <Provider>
              {children}
          </Provider>
      );
  }

• src/contexts/graphql/provider-client.ts:

  "use client";
  
  import React, { useMemo } from "react";
  import {cacheExchange, createClient, fetchExchange, ssrExchange, UrqlProvider} from "@urql/next";
  
  export function GraphqlClientProvider({ children }: React.PropsWithChildren) {
      const [client, ssr] = useMemo(() => {
          const isClient = typeof window !== "undefined";
          const _ssr = ssrExchange({
              isClient,
          });
          const _client = createClient({
              url: "/api/graphql",
              exchanges: [cacheExchange, _ssr, fetchExchange],
              suspense: true,
          });
          return [_client, _ssr]
      }, [])
      return (
          <UrqlProvider  client={client} ssr={ssr}>
              {children}
          </UrqlProvider>
      );
  }

• src/contexts/graphql/provider-server.ts:

  import React from "react";
  import {cacheExchange, createClient, ssrExchange, UrqlProvider} from "@urql/next";
  import {createLocalExecutor} from "@/lib/server.ts";
  
  export async function GraphqlServerProvider({ children }: React.PropsWithChildren) {
      const ssr = ssrExchange({
          isClient: false,
      })
      const executeExchange = await createLocalExecutor();
      const client = createClient({
          url: "/api/graphql",
          exchanges: [cacheExchange, ssr, executeExchange],
          suspense: true,
      });
      return (
          <UrqlProvider client={client} ssr={ssr}>
              {children}
          </UrqlProvider>
      )
  }

[gregbrowndev]

So I found the solution!

I didn't notice the app had logged out an error message on the server because it had been lost within all the output caused by React going into an infinite render loop. However, this was the error:

web-ui:dev: ⨯ Error: Server Functions cannot be called during initial render. This would create a fetch waterfall. Try to use a Server Component to pass data to Client Components instead.
web-ui:dev: at GraphqlServerProvider (./src/contexts/graphql/provider-server.tsx:20:102)

Removing the "use server" at the top of src/lib/server.ts was enough to fix the issue.

So, I was on the right lines by making two Layout objects to initialise the URQL client. The key one is that the server component can be marked async so it waits for the client to be initialised before rendering. A lot of trial and error over nearly a full week, but I got there in the end.