> ## Documentation Index
> Fetch the complete documentation index at: https://aomilabs-victor-docs-redirect-build-overview.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Frontend Setup

> Set up the Aomi chat widget in a Next.js 15 app as a product surface: prerequisites, shadcn install, environment configuration, and widget mounting steps.

<Info>
  Looking for install steps? See the [Quickstart](/getting-started/quickstart) for the one-command shadcn install.
</Info>

This page covers what the Aomi widget gives you, how it slots into a Next.js app, and how to decide between the widget and the headless library.

## When to use the widget

| Use the widget when                                         | Use the headless library when       |
| ----------------------------------------------------------- | ----------------------------------- |
| You want a production-ready chat UI in minutes              | You need a fully custom UI          |
| You're already on shadcn / Tailwind                         | You're not using shadcn             |
| Standard layout (sidebar + thread + composer) works for you | You need a non-standard layout      |
| You want to edit source files when needed                   | You want to compose from primitives |

→ [Headless Library](/guides/headless-library) covers the alternative path.

## What the widget gives you

* **Full chat surface**: sidebar with threads, message composer, streaming thread view.
* **ControlBar**: model selector, app selector, API key input, wallet connect, network select.
* **Wallet pipeline**: Para-backed connect, wagmi-compatible signing, simulation-first transaction handling.
* **Compound component API**: drop in only the pieces you want.
* **Owned source**: components are copied into your repo via shadcn; edit anything.

## Anatomy

```text theme={null}
your-app/
├── components/
│   ├── aomi-frame.tsx          ← Main shell (Root, Header, Composer)
│   ├── control-bar/            ← Model, App, API key, Wallet, Network
│   ├── assistant-ui/           ← Thread, ThreadList, markdown, tools
│   ├── ui/                     ← shadcn primitives
│   └── runtime-tx-handler.tsx  ← Runtime transaction handler
└── lib/utils.ts
```

Three registries feed the install:

| Source               | What                                                  | Why                                            |
| -------------------- | ----------------------------------------------------- | ---------------------------------------------- |
| `aomi.dev/r`         | Customized components (AomiFrame, Thread, ThreadList) | Aomi-specific features like wallet integration |
| `r.assistant-ui.com` | Upstream primitives (markdown, tooltips)              | Receives upstream fixes                        |
| `ui.shadcn.com`      | Primitives (Button, Sidebar, Dialog)                  | Standard UI building blocks                    |

## Where it lives in your app

A typical setup mounts `AomiFrame` on a dedicated route:

```tsx theme={null}
// app/chat/page.tsx
import { AomiFrame } from "@/components/aomi-frame";

export default function ChatPage() {
  return (
    <div style={{ height: "100vh" }}>
      <AomiFrame
        backendUrl={process.env.NEXT_PUBLIC_BACKEND_URL!}
        height="100%"
        width="100%"
      />
    </div>
  );
}
```

For embedded layouts (sidebars, modals, panels), use the [compound API](/guides/widget-installation#compound-component-api).

## Next steps

* [Quickstart](/getting-started/quickstart): install with one command.
* [Widget Installation](/guides/widget-installation): props, compound API, and customization.
* [Headless Library](/guides/headless-library): build your own UI.
* [Apps & Auth](/reference/apps-auth): how API keys and apps work.