# 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**](https://auth.faustine.ai/go?to=%2Fweb-assistants) 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](https://docs.faustine.ai/web-agents/nextjs-adapter/).

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`.

```bash
npx skills add faustine-ai/skills
```

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

```text
/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](https://docs.faustine.ai/packages/agent-skills/).

## Install by hand

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

### Add the packages

**npm**

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

**pnpm**

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

**yarn**

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

**bun**

```bash
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.

```tsx filename="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} />;
}
```

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

```tsx filename="app/layout.tsx"
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](https://docs.faustine.ai/technologies/nextjs-pages-router/).

### 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`.

> **Warning:** Do not give the variable a `NEXT_PUBLIC_` prefix. Next.js puts variables with that prefix in the browser bundle, and anyone with the secret can sign a token for any user.

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`.

```tsx filename="app/faustine-agent.tsx"
<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

| Symptom | Cause | Fix |
| --- | --- | --- |
| The page fails with an error that starts `faustineIdentityToken: set FAUSTINE_IDENTITY_SECRET` | The server environment has no secret. | Set `FAUSTINE_IDENTITY_SECRET`, or call the helper only when the variable is set. |
| The user shows as anonymous in the **Monitoring** tab | The token was signed with another agent's secret. | Copy the secret from this agent's **Identity verification** section. |

## Next steps

- [The Faustine adapter for Next.js](https://docs.faustine.ai/web-agents/nextjs-adapter/): let the agent call Server Actions and server-only data functions.
- [Identity verification](https://docs.faustine.ai/web-agents/identity-verification/): what a verified user gets.
- [@faustine-ai/next reference](https://docs.faustine.ai/reference/next-package/): every prop and option of the package.
- [Next.js on Faustine](https://docs.faustine.ai/technologies/nextjs/): what each feature does in a Next.js app.