@faustine-ai/next | Faustine Docs

@faustine-ai/next is the npm package for a Web Agent in a Next.js app. It has a component that mounts the agent, a helper that signs the user's identity on the server, and the adapter that lets the agent call Server Actions and server-only data functions.


Version	0.1.5
Command	`faustine-next`
Requires	Next.js 14 or later, React 18 or later, `@faustine-ai/web-agent` 0.2.0 or later
License	MIT
npm	@faustine-ai/next
Source	faustine-ai/next

What is in it

Part	Import or command	Router
`<FaustineAgent>`, the component that mounts the agent	`@faustine-ai/next/client`	App Router, Pages Router
`faustineIdentityToken`, which signs the identity token	`@faustine-ai/next`	App Router, Pages Router
`createRegistry` and `createFaustineHandler`, the adapter's runtime	`@faustine-ai/next`	App Router
`withFaustine`, which records the build's commit	`@faustine-ai/next`	App Router
`faustine-next`, the generator with `init`, `sync` and `doctor`	`npx faustine-next`	App Router

The adapter needs the App Router. faustine-next stops when the project has no app/ or src/app/ directory. A Pages Router app uses the component and the identity helper only.

Install

terminal

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

terminal

pnpm add @faustine-ai/next @faustine-ai/web-agent

terminal

yarn add @faustine-ai/next @faustine-ai/web-agent

terminal

bun add @faustine-ai/next @faustine-ai/web-agent

@faustine-ai/web-agent is the loader the component uses. The two are installed together.

app/faustine-agent.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 is exported from its own entry point so that server code which imports @faustine-ai/next does not pull in React or the loader.

Next steps

Next.js (App Router) quickstart: mount the agent and sign the identity in the root layout.
Next.js (Pages Router) quickstart: mount the agent from pages/_app.tsx.
The Faustine adapter for Next.js: what the registry and the route handler do.
@faustine-ai/next reference: props, options and responses.
faustine-next CLI: commands, flags and exit codes.