Skip to main content

Module: nextjs

Helpers for integrating Convex into Next.js applications using server rendering.

This module contains:

  1. preloadQuery, for preloading data for reactive client components.
  2. fetchQuery, fetchMutation and fetchAction for loading and mutating Convex data from Next.js Server Components, Server Actions and Route Handlers.

Usage

All exported functions assume that a Convex deployment URL is set in the NEXT_PUBLIC_CONVEX_URL environment variable. npx convex dev will automatically set it during local development.

Preloading data

Preload data inside a Server Component:

import { preloadQuery } from "convex/nextjs";
import { api } from "@/convex/_generated/api";
import ClientComponent from "./ClientComponent";

export async function ServerComponent() {
const preloaded = await preloadQuery(api.foo.baz);
return <ClientComponent preloaded={preloaded} />;
}

And pass it to a Client Component:

import { Preloaded, usePreloadedQuery } from "convex/nextjs";
import { api } from "@/convex/_generated/api";

export function ClientComponent(props: {
preloaded: Preloaded<typeof api.foo.baz>;
}) {
const data = await usePreloadedQuery(props.preloaded);
// render `data`...
}

Type Aliases

NextjsOptions

Ƭ NextjsOptions: Object

Options to preloadQuery, fetchQuery, fetchMutation and fetchAction.

Type declaration

NameTypeDescription
token?stringThe JWT-encoded OpenID Connect authentication token to use for the function call.
url?stringThe URL of the Convex deployment to use for the function call. Defaults to process.env.NEXT_PUBLIC_CONVEX_URL.
skipConvexDeploymentUrlCheck?booleanSkip validating that the Convex deployment URL looks like https://happy-animal-123.convex.cloud or localhost. This can be useful if running a self-hosted Convex backend that uses a different URL. The default value is false

Defined in

nextjs/index.ts:60

Functions

preloadQuery

preloadQuery<Query>(query, ...args): Promise<Preloaded<Query>>

Execute a Convex query function and return a Preloaded payload which can be passed to usePreloadedQuery in a Client Component.

Type parameters

NameType
Queryextends FunctionReference<"query">

Parameters

NameTypeDescription
queryQuerya FunctionReference for the public query to run like api.dir1.dir2.filename.func.
...argsArgsAndOptions<Query, NextjsOptions>The arguments object for the query. If this is omitted, the arguments will be {}.

Returns

Promise<Preloaded<Query>>

A promise of the Preloaded payload.

Defined in

nextjs/index.ts:99


preloadedQueryResult

preloadedQueryResult<Query>(preloaded): FunctionReturnType<Query>

Returns the result of executing a query via preloadQuery.

Type parameters

NameType
Queryextends FunctionReference<"query">

Parameters

NameTypeDescription
preloadedPreloaded<Query>The Preloaded payload returned by preloadQuery.

Returns

FunctionReturnType<Query>

The query result.

Defined in

nextjs/index.ts:118


fetchQuery

fetchQuery<Query>(query, ...args): Promise<FunctionReturnType<Query>>

Execute a Convex query function.

Type parameters

NameType
Queryextends FunctionReference<"query">

Parameters

NameTypeDescription
queryQuerya FunctionReference for the public query to run like api.dir1.dir2.filename.func.
...argsArgsAndOptions<Query, NextjsOptions>The arguments object for the query. If this is omitted, the arguments will be {}.

Returns

Promise<FunctionReturnType<Query>>

A promise of the query's result.

Defined in

nextjs/index.ts:134


fetchMutation

fetchMutation<Mutation>(mutation, ...args): Promise<FunctionReturnType<Mutation>>

Execute a Convex mutation function.

Type parameters

NameType
Mutationextends FunctionReference<"mutation">

Parameters

NameTypeDescription
mutationMutationA FunctionReference for the public mutation to run like api.dir1.dir2.filename.func.
...argsArgsAndOptions<Mutation, NextjsOptions>The arguments object for the mutation. If this is omitted, the arguments will be {}.

Returns

Promise<FunctionReturnType<Mutation>>

A promise of the mutation's result.

Defined in

nextjs/index.ts:153


fetchAction

fetchAction<Action>(action, ...args): Promise<FunctionReturnType<Action>>

Execute a Convex action function.

Type parameters

NameType
Actionextends FunctionReference<"action">

Parameters

NameTypeDescription
actionActionA FunctionReference for the public action to run like api.dir1.dir2.filename.func.
...argsArgsAndOptions<Action, NextjsOptions>The arguments object for the action. If this is omitted, the arguments will be {}.

Returns

Promise<FunctionReturnType<Action>>

A promise of the action's result.

Defined in

nextjs/index.ts:174