Next.js API reference

The reference for @aventara/next and the two entries aventara-build --client generates. For how to use them, see Next.js host and TanStack Query and SWR.

Package

Aventara(options)

Hosts a framework. It returns at once and builds nothing; the framework is built on first use, or by ready(), once.

export const { handlers, avClient, avApp, ready } = Aventara({
  ...aventaraConfig,
  adapter: () => createPrismaAdapter({ ...adapter, client: prisma() }),
  prebuilt: process.env.NODE_ENV === "production" ? aventaraContracts : undefined,
  state: async ({ headers }) => ({ user: await userOf(headers.get("authorization")) }),
});

Options: a configuration

On Next.js, mcp must carry authorization ({ path, authorization: { servers, verify } }). Written without it, it is a type error on the Aventara({...}) call. A configuration typed as AvConfig compiles and is refused when the framework is built.

Options: a framework you built

A configuration key beside framework is a type error, and refused when Aventara() is called.

Members

The types are exported so that a project emitting declarations (declaration: true) can write export const { handlers, avClient, avApp, ready } = Aventara(...) with no annotation. avClient.transaction is AvNextClientTransaction and avApp.transaction is AvNextAppTransaction. AvNextStateContext is the state option's parameter ({ headers, request? }), for a state function written in its own file.

avClient

options is AvExecutionOptions: requestId, state (used as given instead of the request's), as (the principal the policy checks). See Server-side usage.

Each call first awaits Next's io(): under cacheComponents, a page that calls avClient or avApp needs <Suspense>, "use cache" or export const instant = false (Next.js host).

state runs once per server render, however many calls the render makes, and once per call outside a render (a Server Action, a route handler of your own). A refusal throws its AvError class (Error codes).

avApp

A list that mixes avClient.tx and avApp.appTx handles is a type error, and refused at runtime (A2004).

A Resource the client layer shows as tx or transaction, or the application layer as appTx or transaction, would hide behind that member. The framework's build fails with AvConstructionError, code COMPILER_RESERVED_RESOURCE_NAME, naming each clash. Rename the model, or hide it from that layer.

avDehydrate

import { avDehydrate } from "@aventara/next";

avDehydrate(data: unknown): unknown

Server side. Copies data, turning each Date, bigint, Uint8Array and decimal into a tagged plain object that React can pass from a Server Component to a Client Component. Arrays and plain objects are copied with their members dehydrated; anything else is returned as it is. Use it as TanStack Query's dehydrate(queryClient, { serializeData: avDehydrate }), or on an SWR fallback.

Throws TypeError for a Date that has no wire form (an invalid date, or a year past four digits).

@/aventara/client (generated)

src/aventara/client.ts, written by aventara-build --client. Import it in Client Components.

AvClient is exported as a type only; the client's calls and options are those of the generated client. The files import nothing from @aventara/client or @aventara/next; universal.ts imports io from next/cache.

@/aventara/universal (generated)

src/aventara/universal.ts, written by aventara-build --client.

Errors

What the Next.js host raises, with the message:

On the routes, every answer is the protocol's: a wrong method on an operation route is 405 (A2012) with Allow, an unknown content coding 415 (A2011), a body over limits.maxRequestBytes 413, and a path the protocol does not own goes to Next's notFound(). See HTTP protocol.

See also

• Next.js host
• Server-side usage: serverClient, application and their options.
• Client API reference: the generated client's calls.
• CLI reference: aventara-build --client.