chore: migrate to agents-ui (#308)

Author: thomasyuill-livekit

README.md

@@ -1,6 +1,6 @@
 # Agent Starter for React
 
-This is a starter template for [LiveKit Agents](https://docs.livekit.io/agents) that provides a simple voice interface using the [LiveKit JavaScript SDK](https://github.com/livekit/client-sdk-js). It supports [voice](https://docs.livekit.io/agents/start/voice-ai), [transcriptions](https://docs.livekit.io/agents/build/text/), and [virtual avatars](https://docs.livekit.io/agents/integrations/avatar).
+This is a starter template for [LiveKit Agents](https://docs.livekit.io/agents) that provides a simple voice interface using [Agents UI](https://livekit.io/ui) components and [LiveKit JavaScript SDK](https://github.com/livekit/client-sdk-js). It supports [voice](https://docs.livekit.io/agents/start/voice-ai), [transcriptions](https://docs.livekit.io/agents/build/text/), and [virtual avatars](https://docs.livekit.io/agents/integrations/avatar).
 
 Also available for:
 [Android](https://github.com/livekit-examples/agent-starter-android) • [Flutter](https://github.com/livekit-examples/agent-starter-flutter) • [Swift](https://github.com/livekit-examples/agent-starter-swift) • [React Native](https://github.com/livekit-examples/agent-starter-react-native)
@@ -25,27 +25,63 @@ This template is built with Next.js and is free for you to use or modify as you
 
 ### Project structure
 
+This starter uses the [Agents UI](https://livekit.io/ui) components for core UI elements like media controls, audio visualizers, chat transcripts, and providing session data. Shadcn installs components into `components/` folder so you can customize them like any other local component.
+
 ```
 agent-starter-react/
 ├── app/
-│   ├── (app)/
 │   ├── api/
-│   ├── components/
-│   ├── fonts/
-│   ├── globals.css
-│   └── layout.tsx
 ├── components/
-│   ├── livekit/
-│   ├── ui/
-│   ├── app.tsx
-│   ├── session-view.tsx
-│   └── welcome.tsx
+│   ├── agents-ui/     - Agents UI components
+│   ├── ai-elements/   - AI Elements components
+│   ├── app/           - App-specific components
+│   ├── ui/            - Primitive shadcn/ui components
+├── fonts/
 ├── hooks/
 ├── lib/
 ├── public/
 └── package.json
 ```
 
+Business logic lives within the `components/app` folder. It's here where the application's state and behavior is managed and the various Shadcn UI components are composed together.
+
+| File                  | Description                                                                                                                                           |
+| --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `session-view.tsx`    | Initializes the application, and LiveKit session. Renders the view controller and session UI including chat transcript, media tiles, and control bar. |
+| `view-controller.tsx` | Manages the transitions between the welcome and session views based on the LiveKit session state.                                                     |
+| `welcome-view.tsx`    | Renders the welcome UI when the LiveKit session is not connected.                                                                                     |
+| `chat-transcript.tsx` | Manages the chat transcript transitions.                                                                                                              |
+| `tile-layout.tsx`     | Manages the layout and transition of media tiles in various application states.                                                                       |
+
+### Component usage
+
+Most Agents UI components require access to a LiveKit session object for access to values like agent state or audio tracks. A Session object can be created from a [TokenSource](/reference/client-sdk-js/variables/TokenSource.html), and provided by wrapping the component in an [AgentSessionProvider](/reference/components/shadcn/component/agent-session-provider).
+
+See [`components/app/app.tsx`](./components/app/app.tsx) for an example of how this is done in this app.
+
+### Customizing components
+
+Agents UI components, like most Shadcn compopnents, take as many primitive attributes as possible. For example, the [AgentControlBar](/reference/components/shadcn/component/agent-control-bar/page.mdoc) component extends `HTMLAttributes<HTMLDivElement>`, so you can pass any props that a div supports. This makes it easy to extend the component with your own styles or functionality.
+
+You can edit any Agents UI component's source code in the `components/agents-ui` directory. For style changes, we recommend passing in tailwind classes to override the default styles. Take a look at the source code to get a sense of how to override a component's default styles.
+
+### Updating components
+
+To update the Agents UI components to the latest publication, run the following command:
+
+```bash
+pnpm shadcn:install
+```
+
+> [!NOTE]
+> The CLI will ask before overwriting any modified files so you can avoid losing any customizations you might have made.
+
+### Installing components
+
+```bash
+pnpm dlx shadcn@latest add @agents-ui/{component-name-a} @agents-ui/{component-name-b}
+```
+
 ## Getting started
 
 > [!TIP]

app/(app)/layout.tsx

@@ -3,7 +3,8 @@ import localFont from 'next/font/local';
 import { headers } from 'next/headers';
 import { ThemeProvider } from '@/components/app/theme-provider';
 import { ThemeToggle } from '@/components/app/theme-toggle';
-import { cn, getAppConfig, getStyles } from '@/lib/utils';
+import { cn } from '@/lib/shadcn/utils';
+import { getAppConfig, getStyles } from '@/lib/utils';
 import '@/styles/globals.css';
 
 const publicSans = Public_Sans({
@@ -45,8 +46,8 @@ interface RootLayoutProps {
 export default async function RootLayout({ children }: RootLayoutProps) {
   const hdrs = await headers();
   const appConfig = await getAppConfig(hdrs);
-  const { pageTitle, pageDescription } = appConfig;
   const styles = getStyles(appConfig);
+  const { pageTitle, pageDescription, companyName, logo, logoDark } = appConfig;
 
   return (
     <html
@@ -70,6 +71,35 @@ export default async function RootLayout({ children }: RootLayoutProps) {
           enableSystem
           disableTransitionOnChange
         >
+          <header className="fixed top-0 left-0 z-50 hidden w-full flex-row justify-between p-6 md:flex">
+            <a
+              target="_blank"
+              rel="noopener noreferrer"
+              href="https://livekit.io"
+              className="scale-100 transition-transform duration-300 hover:scale-110"
+            >
+              {/* eslint-disable-next-line @next/next/no-img-element */}
+              <img src={logo} alt={`${companyName} Logo`} className="block size-6 dark:hidden" />
+              {/* eslint-disable-next-line @next/next/no-img-element */}
+              <img
+                src={logoDark ?? logo}
+                alt={`${companyName} Logo`}
+                className="hidden size-6 dark:block"
+              />
+            </a>
+            <span className="text-foreground font-mono text-xs font-bold tracking-wider uppercase">
+              Built with{' '}
+              <a
+                target="_blank"
+                rel="noopener noreferrer"
+                href="https://docs.livekit.io/agents"
+                className="underline underline-offset-4"
+              >
+                LiveKit Agents
+              </a>
+            </span>
+          </header>
+
           {children}
           <div className="group fixed bottom-0 left-1/2 z-50 mb-2 -translate-x-1/2">
             <ThemeToggle className="translate-y-20 transition-transform delay-150 duration-300 group-hover:translate-y-0" />

app/layout.tsx

@@ -10,12 +10,16 @@
     "cssVariables": true,
     "prefix": ""
   },
+  "iconLibrary": "lucide",
   "aliases": {
     "components": "@/components",
-    "utils": "@/lib/utils",
+    "utils": "@/lib/shadcn/utils",
     "ui": "@/components/ui",
-    "lib": "@/lib",
+    "lib": "@/lib/shadcn",
     "hooks": "@/hooks"
   },
-  "iconLibrary": "phosphor"
+  "registries": {
+    "@agents-ui": "https://livekit.io/ui/r/{name}.json",
+    "@ai-elements": "https://registry.ai-sdk.dev/{name}.json"
+  }
 }