# NPM overview

Two packages, one origin:

- **`@livelayer/react`** — the React-native widget. `<!-- omitted: AvatarWidget -->` component, hooks (`useLiveKitSession`, `useCollect`), page-aware children (`LiveLayerRegion`).
- **`@livelayer/sdk`** — framework-agnostic. Web component (`<livelayer-widget>`), `LiveKitSession` class, `LiveLayerTracker`, capability runner. The React package wraps this; you can also use it directly from Vue, Svelte, vanilla JS, or anywhere else.

This is the path with the most power and the most setup. Reach for it when:

- Your app is React-based and the agent should access component state.
- You need the agent to fill or submit forms in your app.
- You need the agent to read text from your visible DOM.
- You need a fully custom UI — your own avatar dock, your own controls.
- You need an SSO-aware session minted by your own backend.
- You want to build something live-layer doesn't ship out of the box (custom layouts, multi-agent dashboards, embedded coaching tools).

## Install

```bash title="install.sh"
npm install @livelayer/react @livelayer/sdk
# or
pnpm add @livelayer/react @livelayer/sdk
# or
yarn add @livelayer/react @livelayer/sdk
```

The React package depends on the SDK, so installing both keeps you on a consistent version. They're released together.

**Peer dependencies:**

- `react >= 18.0.0`
- `react-dom >= 18.0.0`
- `livekit-client ^2.17.3` — installed automatically; do not duplicate

## Hello world

```tsx title="app.tsx"
import { AvatarWidget } from "@livelayer/react";
import "@livelayer/react/styles.css";

export default function App() {
  return <!-- omitted: AvatarWidget -->;
}
```

That's it. The widget connects to `app.livelayer.studio`, fetches your published agent's config, and mounts a floating bubble.

## What's next

The rest of these docs are the deep dive.

### React API

- **[Quickstart](/docs/develop/npm/react/quickstart)** — minimal app + the most common props you'll touch first
- **[`AvatarWidget` reference](/docs/develop/npm/react/avatar-widget)** — every prop, every callback, every ref method
- **[Page awareness](/docs/develop/npm/react/page-awareness)** — `extractPageContext`, `LiveLayerRegion`. Auto-discovered forms (no wrapper components). Lets the agent see what's on the page.
- **[Data collection](/docs/develop/data-collection)** — `onCollect`, `useCollect`, structured TaskGroup-driven Q&A. Voice-first form filling with per-kind normalization.
- **[Routing](/docs/develop/npm/react/routing)** — `showOn` / `hideOn`, `onNavigate`, hooking into Next.js / React Router
- **[Controlled session](/docs/develop/npm/react/controlled-session)** — own the LiveKit room yourself for cross-page persistence or shared rooms
- **[Theming](/docs/develop/npm/react/theming)** — `branding`, `chromeless`, `compactControls`, custom layouts
- **[Hooks](/docs/develop/npm/react/hooks)** — `useLiveKitSession`, `useAudioLevel`, `useMicrophoneState`, et al. Build your own UI from primitives.

### Framework-agnostic SDK

- **[SDK overview](/docs/develop/npm/sdk/overview)** — when to use the SDK directly
- **[`<livelayer-widget>` web component](/docs/develop/npm/sdk/livelayer-widget)** — Vue, Svelte, vanilla JS
- **[`LiveKitSession` class](/docs/develop/npm/sdk/livekit-session)** — programmatic session lifecycle
- **[`LiveLayerTracker`](/docs/develop/npm/sdk/tracker)** — visitor identity and event tracking

### Types

- **[TypeScript types](/docs/develop/npm/types)** — `AgentState`, `ConnectionState`, `TranscriptEntry`, `AgentCommand`, etc.

## When NOT to use NPM

If you fit any of these, take an easier path first:

- **Marketing site, no React, just want a bubble** → [Script tag](/docs/develop/script-tag/overview) is one line of HTML.
- **Sharing the agent in email or QR codes** → [Hosted URL](/docs/develop/hosted/overview) is zero code.
- **Embedding inside a CMS that won't run scripts** → [Iframe embed](/docs/develop/hosted/iframe).

The NPM path is also the one you can graduate to later — switching from the script tag to the React component is straightforward, the agent IDs and dashboard configuration carry over.