enhancement(convex/nextjs): add better support for using preloadQuery with authenticated requests

[WestBrian]

Enhancement request

It would be nice to have some better support for using the preloadQuery to fetch authenticated requests.

Problem

The issue arises when fetching authenticated data (using Clerk in this case) on the server and passing it to the client. The usePreloadedQuery hook subscribes to the data before the authentication check completes, causing the call to fail. As noted in the docs, "Make sure that the component calling this query is a child of <Authenticated> from convex/react. Otherwise, it will throw on page load." However, this requirement defeats the purpose of preloading, since it forces the UI to wait for client-side authentication before rendering.

Current workarounds

Option 1

Here is a wrapper component I made that will display the preloaded query while the client authenticates and then use the hook once authentication completes.

'use client'

import {
  type Preloaded,
  Authenticated,
  AuthLoading,
  usePreloadedQuery,
} from "convex/react";
import type { FunctionReference } from "convex/server";
import { preloadedQueryResult } from "convex/nextjs";

interface PreloadedWrapperProps<T extends FunctionReference<"query">> {
  preloadedData: Preloaded<T>;
  render: (data: ReturnType<typeof preloadedQueryResult<T>>) => React.ReactNode;
}

const AuthenticatedRender = <T extends FunctionReference<"query">>(
  props: PreloadedWrapperProps<T>
) => {
  const authenticatedData = usePreloadedQuery(props.preloadedData);

  return <>{props.render(authenticatedData)}</>;
};

export const PreloadedWrapper = <T extends FunctionReference<"query">>(
  props: PreloadedWrapperProps<T>
) => {
  const preloadedData = preloadedQueryResult(props.preloadedData);

  return (
    <>
      <AuthLoading>{props.render(preloadedData)}</AuthLoading>
      <Authenticated>
        <AuthenticatedRender {...props} />
      </Authenticated>
    </>
  );
};

Usage looks like this:

<PreloadedWrapper preloadedData={props.preloadedTasks} render={(tasks) => (
  <div>...</div>
)} />

This comes with some drawbacks though like not being able to interweave server and client components.

Option 2

Custom usePreloadQueryWithAuth. Here is the implementation for quick reference:

import { preloadedQueryResult } from 'convex/nextjs';
import { Preloaded, usePreloadedQuery } from 'convex/react';
import { FunctionReference } from 'convex/server';

// Returns the result from server while the client
// is being authenticated.
// This assumes:
//  1. The query only returns `null` when it's waiting for auth
//  2. The query is always authenticated when called from the server
export function usePreloadedQueryWithAuth<
  Query extends FunctionReference<'query'>,
>(preloadedQuery: Preloaded<Query>): Exclude<Query['_returnType'], null> {
  const loaded = usePreloadedQuery(preloadedQuery);
  return loaded ?? preloadedQueryResult(preloadedQuery);
}

[thomasballinger]

How about an option for the client to wait to run any queries/mutations/actions until auth has been sent? So for the first say ~100-1s the page will be sitting there showing the SSRed content and the live-synced data doesn't take over the queries have auth. I think authed queries are the default in many apps and the client-side <Authenticated> solutions are a bummer for those cases.

Here are two new constructor option ideas: authMode: 'waitForAuth' to do the above, and initialAuth which is for a JWT passed from the server, which just speeds things up a bit.

// module_level
const GLOBAL_CONVEX_CLIENT = new ConvexClient(url, {
  // When authMode is 'waitForAuth', no queries or mutations will run
  // until auth has been sent. (or maybe until it has been acknowledged, if there's a race here)
  authMode: 'waitForAuth',
  // initialAuth implies the above, and is a token or Promise<token>
  // to use for auth. It's probably passed from a server-side render
  // or server component. Ideally it's the same token that was used
  // for the SSR render, so this delay is as short as possible.
  initialAuth: getAuth()
})

[thomasballinger]

Another user suggested specifying on a query level which queries need auth, that's reasonable once we have query options, e.g. useQuery(api.authed.listData, args, { waitForAuth: true }). We could do this too, ideally this would be information reflected in the types so the exported queries/mutations/actions can declare that they should not be run without auth. I like the global default behavior because authed queries are the default in many apps, I'd rather that path just work.