Module: nextjs

For AI agents: see llms.txt for the complete documentation index. Markdown versions are available by adding .md to a page URL or requesting Accept: text/markdown.

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/react";
import { api } from "@/convex/_generated/api";

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

Type Aliases

NextjsOptions

Ƭ NextjsOptions: Object

Options to preloadQuery, fetchQuery, fetchMutation and fetchAction.

Type declaration

Name	Type	Description
token?	string	The JWT-encoded OpenID Connect authentication token to use for the function call.
url?	string	The URL of the Convex deployment to use for the function call. Defaults to process.env.NEXT_PUBLIC_CONVEX_URL if not provided. Explicitly passing undefined here (such as from missing ENV variables) will throw an error in the future.
skipConvexDeploymentUrlCheck?	boolean	Skip 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:61

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

Name	Type
Query	extends FunctionReference<"query"> | FunctionReference_future<"query">

Parameters

Name	Type	Description
query	Query	a FunctionReference for the public query to run like api.dir1.dir2.filename.func.
...args	ArgsAndOptions<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:102

---

preloadedQueryResult

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

Returns the result of executing a query via preloadQuery.

Type parameters

Name	Type
Query	extends FunctionReference<"query"> | FunctionReference_future<"query">

Parameters

Name	Type	Description
preloaded	Preloaded<Query>	The Preloaded payload returned by preloadQuery.

Returns

FunctionReturnType<Query>

The query result.

Defined in

nextjs/index.ts:123

---

fetchQuery

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

Execute a Convex query function.

Type parameters

Name	Type
Query	extends FunctionReference<"query"> | FunctionReference_future<"query">

Parameters

Name	Type	Description
query	Query	a FunctionReference for the public query to run like api.dir1.dir2.filename.func.
...args	ArgsAndOptions<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:139

---

fetchMutation

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

Execute a Convex mutation function.

Type parameters

Name	Type
Mutation	extends FunctionReference<"mutation"> | FunctionReference_future<"mutation">

Parameters

Name	Type	Description
mutation	Mutation	A FunctionReference for the public mutation to run like api.dir1.dir2.filename.func.
...args	ArgsAndOptions<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:160

---

fetchAction

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

Execute a Convex action function.

Type parameters

Name	Type
Action	extends FunctionReference<"action"> | FunctionReference_future<"action">

Parameters

Name	Type	Description
action	Action	A FunctionReference for the public action to run like api.dir1.dir2.filename.func.
...args	ArgsAndOptions<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:183