@faustine-ai/next reference

@faustine-ai/next mounts a Web Agent in a Next.js app, signs the user's identity on the server and runs the adapter's route handler. This page describes version 0.1.5.

Usage

npm install @faustine-ai/next @faustine-ai/web-agent

The package has two entry points. Import the component from @faustine-ai/next/client and everything else from @faustine-ai/next, which is for server code.

Peer dependencies: next 14 or later, react 18 or later, @faustine-ai/web-agent 0.2.0 or later.

FaustineAgent

A client component that starts the agent once and renders nothing. Render it one time, from the root layout or pages/_app.tsx.

'use client';
import { FaustineAgent } from '@faustine-ai/next/client';

export default function Agent({ identityJwt }: { identityJwt?: string | null }) {
  return <FaustineAgent agentId="<AGENT_ID>" identityJwt={identityJwt} />;
}

The component calls Faustine.init from @faustine-ai/web-agent in an effect. React Strict Mode runs the effect twice and the second call returns the same instance.

faustineIdentityToken

faustineIdentityToken(user: IdentityUser, options?: IdentityTokenOptions): string

Signs the identity token for a user with HS256 and returns it. Call it in server code only.

The token has the claims sub, iat and exp, plus name and email when given. The function throws when there is no secret or no user.id.

import { faustineIdentityToken } from '@faustine-ai/next';

const identityJwt = faustineIdentityToken(
  { id: user.id, name: user.name, email: user.email },
  { expiresIn: 900 },
);

createRegistry

createRegistry(meta: RegistryMeta, map: Record<string, OperationBinding>): Registry

Builds the registry the handler serves. npx faustine-next init generates the call in faustine/registry.ts. The names are validated when the module loads, so a malformed registry fails the build of your app.

Each binding has these fields.

How params maps the JSON input to the call:

The returned Registry has webAgent, formatVersion, operations (the names, sorted), hash (16 hexadecimal characters) and bindings.

createFaustineHandler

createFaustineHandler(registry: Registry, options?: FaustineHandlerOptions): { GET, POST }

Returns the two functions of the catch-all route handler.

import { createFaustineHandler } from '@faustine-ai/next'
import registry from '@/faustine/registry'

export const { GET, POST } = createFaustineHandler(registry)

GET /api/faustine/manifest

Answers what the build serves. Any other GET path answers 404.

POST /api/faustine/<operation>

Runs the bound function with the JSON body as input. An empty body is an empty object. If the binding has a schema, the function receives the validated value.

Every error body also has a message. Every response has the x-faustine-registry header with the registry hash, and x-faustine-build when the build's commit is known.

When a request to Faustine fails, the handler reuses the last list of enabled operations for up to 10 times manifestTtlMs.

withFaustine

withFaustine(nextConfig?: NextConfig): NextConfig

Wraps the Next.js config and sets env.FAUSTINE_BUILD_SHA to the commit of the build. It reads the first of these variables that is set: FAUSTINE_BUILD_SHA, VERCEL_GIT_COMMIT_SHA, GITHUB_SHA, CF_PAGES_COMMIT_SHA, COMMIT_REF, SOURCE_VERSION. With none set it returns the config unchanged.

import type { NextConfig } from 'next';
import { withFaustine } from '@faustine-ai/next';

const nextConfig: NextConfig = {};

export default withFaustine(nextConfig);

Environment variables

Other exports

The server entry point also exports the types OperationBinding, OperationFn, OperationName, OperationParam, OperationParamKind, OperationSchema, Registry, RegistryMeta, FaustineHandlerOptions, ManifestResponse, ServedManifest, IdentityUser and IdentityTokenOptions. The client entry point exports the type FaustineAgentProps.

Next steps

• faustine-next CLI: the generator that writes the registry and the route handler.
• The Faustine adapter for Next.js: how the registry and the handler fit together.
• JavaScript API: the init and identify calls the component makes, and logout, which you call yourself.