Module: nextjs
Helpers for integrating Convex into Next.js applications using server rendering.
This module contains:
- preloadQuery, for preloading data for reactive client components.
- 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
| 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. |
Defined in
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"> |
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
preloadedQueryResult
▸ preloadedQueryResult<Query>(preloaded): FunctionReturnType<Query>
Returns the result of executing a query via preloadQuery.
Type parameters
| Name | Type |
|---|---|
Query | extends FunctionReference<"query"> |
Parameters
| Name | Type | Description |
|---|---|---|
preloaded | Preloaded<Query> | The Preloaded payload returned by preloadQuery. |
Returns
FunctionReturnType<Query>
The query result.
Defined in
fetchQuery
▸ fetchQuery<Query>(query, ...args): Promise<FunctionReturnType<Query>>
Execute a Convex query function.
Type parameters
| Name | Type |
|---|---|
Query | extends FunctionReference<"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
fetchMutation
▸ fetchMutation<Mutation>(mutation, ...args): Promise<FunctionReturnType<Mutation>>
Execute a Convex mutation function.
Type parameters
| Name | Type |
|---|---|
Mutation | extends FunctionReference<"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
fetchAction
▸ fetchAction<Action>(action, ...args): Promise<FunctionReturnType<Action>>
Execute a Convex action function.
Type parameters
| Name | Type |
|---|---|
Action | extends FunctionReference<"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.