Install in Next.js

Install a Web Agent in a Next.js app with @faustine-ai/next. The package has a component that mounts the agent and a helper that signs the user's identity on the server. A Next.js app does not use the script tag.

Before you begin

• Next.js 14 or later and React 18 or later.
• A Web Agent created for this app with Next.js as its technology, whose analysis has finished.

Copy the install command

To get the command with your agent's ID filled in:

1. In the portal, go to Web Agents and select your agent.
2. In the Overview tab, find the Install the assistant card.
3. If the card shows Create install command, select it. The card shows the button when the analysis found Server Actions or server-only functions, and the command then also installs the Faustine adapter for Next.js.

The setup code in the command can be used once and expires after 30 minutes. New code replaces it.

Install with a coding agent

The card opens on With your coding agent. Run both lines in the directory of the Next.js app, the one with its package.json.

npx skills add faustine-ai/skills

Then, in your coding agent, paste the second line from the card:

/install-faustine <AGENT_ID>

The skill installs the package, mounts the component, signs the identity where your app reads its session, and checks the launcher in the browser. Review the diff, then merge and deploy. See Agent skills.

Install by hand

Select By hand on the card to see these steps with your ID.

Add the packages

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

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

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

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

Mount the component

Create a client component that renders <FaustineAgent>. <AGENT_ID> is the value in the card's Show snippet block.

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

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

Render it once from the root layout, after {children}. The layout stays a Server Component.

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

export default async function RootLayout({ children }: { children: React.ReactNode }) {
  const user = await getSession(); // your own session helper
  const identityJwt = user
    ? faustineIdentityToken({ id: user.id, name: user.name, email: user.email })
    : null;
  return (
    <html lang="en">
      <body>
        {children}
        <Agent identityJwt={identityJwt} />
      </body>
    </html>
  );
}

In a Pages Router app, render the component in pages/_app.tsx and fetch the token from an API route. See the Next.js (Pages Router) quickstart.

Set the identity secret

faustineIdentityToken signs with FAUSTINE_IDENTITY_SECRET and throws when the variable is not set.

1. In the agent's Settings tab, select Identity verification. In the Secret row, select Copy.
2. Add it to the server environment of your app as FAUSTINE_IDENTITY_SECRET.

An app without a session leaves out identityJwt, and its visitors are anonymous.

Deploy

Merge and deploy with your own pipeline. The launcher appears on every page. After a signed-in user sends a message, the conversation in the agent's Monitoring tab shows their name with a Verified badge.

Load another environment

The component loads the Production environment, or the agent's first environment while it has no Production. To load another one, pass its name in env.

<FaustineAgent
  agentId="<AGENT_ID>"
  identityJwt={identityJwt}
  env={process.env.NEXT_PUBLIC_FAUSTINE_ENV}
/>

Set NEXT_PUBLIC_FAUSTINE_ENV only in the deployments that serve an environment other than Production.

If the app uses the adapter, set FAUSTINE_ENV to the same name in those deployments. The route handler reads it to know which environment's version decides what it may run, and uses Production without it.

Troubleshooting

Next steps

• The Faustine adapter for Next.js: let the agent call Server Actions and server-only data functions.
• Identity verification: what a verified user gets.
• @faustine-ai/next reference: every prop and option of the package.
• Next.js on Faustine: what each feature does in a Next.js app.