# Install from npm

`@faustine-ai/web-agent` is the loader for apps that have a bundler. It gives you typed calls to start the agent, identify the user and open the panel. The widget and the agent's actions are not in the package. They load from Faustine when `init` runs.

## Before you begin

- The agent has a version served on the environment the app loads. Publishing the first version serves it on the release target, which is the first environment you selected in the wizard.
- For a Next.js app, use `@faustine-ai/next` instead. See [Install in Next.js](https://docs.faustine.ai/web-agents/install-in-nextjs/).

## Install the package

**npm**

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

**pnpm**

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

**yarn**

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

**bun**

```bash
bun add @faustine-ai/web-agent
```

## Start the agent

To start the agent when your app loads:

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 and select the **npm** tab.
3. Copy the `agentId` value from the snippet.
4. Create a module that calls `init`, and import it from your app's entry file.

```ts filename="src/faustine.ts"
import Faustine from '@faustine-ai/web-agent';

export const agent = Faustine.init({
  agentId: '<AGENT_ID>',
});
```

The agent's launcher appears on the page. `init` returns a handle. Import `agent` wherever your app identifies the user or opens the panel.

A page holds one agent. A second call to `init` returns the handle of the first.

## Load a different environment in development

`init` loads the Production environment, or the agent's first environment while it has no Production, unless you pass `env`. This example loads Staging outside production builds. `import.meta.env.PROD` is the Vite flag. Use your bundler's equivalent.

```ts filename="src/faustine.ts"
import Faustine from '@faustine-ai/web-agent';

export const agent = Faustine.init({
  agentId: '<AGENT_ID>',
  env: import.meta.env.PROD ? 'Production' : 'Staging',
});
```

The environment has to exist and serve a version. See [Deploy a version to an environment](https://docs.faustine.ai/web-agents/deploy-a-version/).

## Identify the user and sign out

Call `identify` when your app knows who the user is, and `logout` when they sign out.

```ts filename="src/auth.ts"
import { agent } from './faustine';

export async function onSignedIn() {
  const me = await fetch('/api/me').then((res) => res.json());
  agent.identify({ jwt: me.faustineJwt });
}

export function onSignedOut() {
  agent.logout();
}
```

`identify` can run before the widget has finished loading. The loader keeps the last call and applies it when the widget is ready. To sign the token, see [Verify your users with a signed token](https://docs.faustine.ai/web-agents/verify-users/).

## Server-side rendering

Importing the package on a server does nothing. `init` called outside a browser returns a handle whose methods do nothing, and logs one warning. In a framework that renders on the server, call `init` from code that runs in the browser only, such as an effect or a mount callback.

## Troubleshooting

| Symptom | Cause | Fix |
| --- | --- | --- |
| The console shows `init called for "…" but "…" is already initialized` | `init` ran twice with different IDs. A page holds one agent. | Call `init` in one module only. |
| The console shows `init called outside a browser` | `init` ran during server-side rendering. | Call `init` from code that runs in the browser only. |
| The console shows `failed to load https://webagent.faustine.ai/embed…` | No environment of the agent serves a version, or the page's domain is not allowed. | Check the response of that request. `404` means nothing is served. `403` means the domain is not in the allowed domains. |

## Next steps

- [JavaScript API](https://docs.faustine.ai/reference/javascript-api/): every option of `init` and every method of the handle.
- [React quickstart](https://docs.faustine.ai/technologies/react/): the same install, step by step, in a React app.
- [Verify your users with a signed token](https://docs.faustine.ai/web-agents/verify-users/): sign the token that `identify` sends.
- [@faustine-ai/web-agent](https://docs.faustine.ai/packages/web-agent/): the package and its versions.