### LlamaIndex Server Setup Example

Source: https://github.com/run-llama/chat-ui/blob/main/packages/server/examples/CLAUDE.md

Demonstrates the standard server setup pattern for LlamaIndex Server. It includes configuring the workflow, UI settings, and the port.

```typescript
new LlamaIndexServer({
  workflow: workflowFactory,
  uiConfig: {
    /* UI configuration */
  },
  port: 3000,
}).start()
```

--------------------------------

### Install Dependencies with uv sync

Source: https://github.com/run-llama/chat-ui/blob/main/examples/llamadeploy/chat/custom-ui/README.md

Installs project dependencies using the uv package manager. This command is essential for setting up the environment for both the SDK and the CLI.

```bash
uv sync
```

--------------------------------

### Install Frontend Dependencies with pnpm

Source: https://github.com/run-llama/chat-ui/blob/main/examples/fastapi/README.md

Installs JavaScript dependencies for the NextJS frontend using pnpm. This command should be run from the 'frontend' directory.

```bash
cd frontend
pnpm install
```

--------------------------------

### Install Dependencies (Bash)

Source: https://github.com/run-llama/chat-ui/blob/main/examples/nextjs/README.md

Installs project dependencies using npm. Ensure Node.js and npm are installed on your system.

```bash
npm install
```

--------------------------------

### Start LlamaIndex Server Example with nodemon and tsx

Source: https://github.com/run-llama/chat-ui/blob/main/packages/server/examples/README.md

Starts a specific LlamaIndex Server example using nodemon for hot-reloading and tsx for running TypeScript files. Replace '<example>' with the desired example directory name.

```bash
pnpm nodemon --exec tsx <example>/index.ts
```

--------------------------------

### Install Dependencies with pnpm

Source: https://github.com/run-llama/chat-ui/blob/main/packages/server/examples/README.md

Installs project dependencies using the pnpm package manager. This is a prerequisite for running the LlamaIndex Server examples.

```bash
pnpm install
```

--------------------------------

### Start Development Server (Bash)

Source: https://github.com/run-llama/chat-ui/blob/main/examples/nextjs/README.md

Starts the Next.js development server for local testing and development.

```bash
npm run dev
```

--------------------------------

### Start FastAPI Development Server

Source: https://github.com/run-llama/chat-ui/blob/main/examples/fastapi/README.md

Starts the FastAPI server for development. This command assumes uv is used for running the server. The API will be accessible at http://localhost:8000.

```bash
uv run fastapi dev
```

--------------------------------

### Install and Run Next.js Development Server

Source: https://github.com/run-llama/chat-ui/blob/main/packages/server/next/README.md

Installs project dependencies and starts the development server for the Next.js application. Access the application at http://localhost:3000.

```bash
npm install
npm run dev
```

--------------------------------

### Workflow Factory Pattern Example

Source: https://github.com/run-llama/chat-ui/blob/main/packages/server/examples/CLAUDE.md

Illustrates the workflow factory pattern used in LlamaIndex Server examples. It shows how to create an agent with a predefined set of tools or with dynamic setup logic.

```typescript
const workflowFactory = () => agent({ tools: [...] });
// or
const workflowFactory = async () => {
  /* setup logic */
  return agent({ tools: [...] });
};
```

--------------------------------

### Run LlamaDeploy API Server

Source: https://github.com/run-llama/chat-ui/blob/main/examples/llamadeploy/chat/custom-ui/README.md

Starts the LlamaDeploy API server locally using Uvicorn. This command is necessary to serve the chat UI and handle workflow requests.

```python
uv run -m llama_deploy.apiserver
```

--------------------------------

### Web App Development Commands (Next.js)

Source: https://github.com/run-llama/chat-ui/blob/main/CLAUDE.md

Manages development and build processes for the Next.js example application. Includes commands for starting the development server, building the application for production, starting the production server, linting, and type checking.

```bash
pnpm dev
pnpm build
pnpm start
pnpm lint
pnpm type-check
pnpm registry:build
```

--------------------------------

### Install @llamaindex/chat-ui via NPM or Shadcn CLI

Source: https://context7.com/run-llama/chat-ui/llms.txt

Provides instructions for installing the @llamaindex/chat-ui library using either npm or the Shadcn CLI. The Shadcn CLI method is recommended for a quicker setup.

```bash
# Option 1: NPM installation
npm install @llamaindex/chat-ui

# Option 2: Shadcn CLI (recommended for quick start)
npx shadcn@latest add https://ui.llamaindex.ai/r/chat.json
```

--------------------------------

### Install LlamaIndex Chat UI Manually (npm, yarn, pnpm, bun)

Source: https://github.com/run-llama/chat-ui/blob/main/docs/chat-ui/getting-started.mdx

Manually install the @llamaindex/chat-ui package along with react and react-dom using your preferred package manager.

```shell
npm install @llamaindex/chat-ui react react-dom
```

```shell
yarn add @llamaindex/chat-ui react react-dom
```

```shell
pnpm add @llamaindex/chat-ui react react-dom
```

```shell
bun add @llamaindex/chat-ui react react-dom
```

--------------------------------

### AI Provider Setup (TypeScript)

Source: https://github.com/run-llama/chat-ui/blob/main/examples/nextjs/README.md

Sets up the AI provider using `createAI` from Vercel AI SDK. It defines server state and UI state, exposing server actions for chat functionality.

```typescript
import {createAI, createStreamableUI, getMutableAIState} from "ai/rsc";
import {ReactNode} from "react";
import {Message} from "ai/react";

export const AIState = {
  messages: [] as { role: "user" | "assistant"; content: string }[];
};

export const UIState = {
  messages: [] as { id: string; role: "user" | "assistant"; content: ReactNode }[];
};

export async function chatAction(content: string) {
  "use server";

  const aiState = getMutableAIState();

  aiState.messages.push({
    role: "user",
    content,
  });

  const stream = createStreamableUI(
    <div>
      {/* Render some loading UI */}
      <p>AI is thinking...</p>
    </div>
  );

  // Simulate a delay and then stream a response
  await new Promise((resolve) => setTimeout(resolve, 1000));

  stream.update(
    <div>
      <p>This is a streamed response!</p>
    </div>
  );

  // Add the assistant's response to the AI state
  aiState.messages.push({
    role: "assistant",
    content: "This is a streamed response!",
  });

  stream.done();

  return {
    stream,
  };
}

export const AI = createAI({
  initial: {
    messages: [],
  },
  >
  ui: {
    "message": ({children}: {
      children: ReactNode;
    }) => (
      <div>{children}</div>
    ),
  },
});
```

--------------------------------

### Quick Start: Initialize and Start LlamaIndex Server

Source: https://github.com/run-llama/chat-ui/blob/main/packages/server/README.md

Demonstrates how to initialize and start the LlamaIndexServer in TypeScript. It imports necessary modules, defines a workflow using an agent and the OpenAI LLM with a Wikipedia tool, and configures the chat UI with starter questions.

```typescript
import { LlamaIndexServer } from '@llamaindex/server'
import { openai } from '@llamaindex/openai'
import { agent } from '@llamaindex/workflow'
import { wiki } from '@llamaindex/tools' // or any other tool

const createWorkflow = () => agent({ tools: [wiki()], llm: openai('gpt-4o') })

new LlamaIndexServer({
  workflow: createWorkflow,
  uiConfig: {
    starterQuestions: ['Who is the first president of the United States?'],
  },
}).start()
```

--------------------------------

### Run Development Server with LlamaIndex

Source: https://github.com/run-llama/chat-ui/blob/main/packages/server/examples/CLAUDE.md

These commands demonstrate how to run the LlamaIndex development server and specific examples. They utilize pnpm and nodemon for package management and file watching.

```bash
pnpm typecheck

pnpm dev

npx nodemon --exec tsx agentic-rag/index.ts
npx nodemon --exec tsx custom-layout/index.ts
npx nodemon --exec tsx devmode/index.ts --ignore src/app/workflow_*.ts
```

--------------------------------

### Example Suggestion Part (TypeScript)

Source: https://github.com/run-llama/chat-ui/blob/main/docs/chat-ui/parts.mdx

An example of a `DataPart` with the type `data-suggested_questions` in TypeScript. This part provides interactive follow-up questions to guide the user's conversation.

```typescript
const suggestionPart = {
  type: 'data-suggested_questions',
  data: [
    'Can you explain the methodology in more detail?',
    'What are the potential limitations?',
    'How does this compare to traditional methods?'
  ]
}
```

--------------------------------

### Full SSE Stream Implementation Example (TypeScript)

Source: https://github.com/run-llama/chat-ui/blob/main/docs/chat-ui/parts.mdx

Provides a complete example of a `ReadableStream` implementation for SSE. It includes functions to write text chunks (start, delta, end) and data chunks, demonstrating the complete streaming protocol for both text and rich data.

```typescript
const fakeChatStream = (parts: (string | MessagePart)[]): ReadableStream => {
  return new ReadableStream({
    async start(controller) {
      const encoder = new TextEncoder()
      
      function writeStream(chunk: TextChunk | DataChunk) {
        controller.enqueue(
          encoder.encode(`${DATA_PREFIX}${JSON.stringify(chunk)}\n\n`)
        )
      }
      
      async function writeText(content: string) {
        const messageId = crypto.randomUUID()
        
        // Start text stream
        writeStream({ id: messageId, type: 'text-start' })
        
        // Stream tokens
        for (const token of content.split(' ')) {
          writeStream({
            id: messageId,
            type: 'text-delta',
            delta: token + ' '
          })
          await new Promise(resolve => setTimeout(resolve, 30))
        }
        
        // End text stream
        writeStream({ id: messageId, type: 'text-end' })
      }
      
      async function writeData(data: MessagePart) {
        writeStream({
          id: data.id,
          type: `data-${data.type}`,
          data: data.data
        })
      }
      
      // Stream all parts
      for (const item of parts) {
        if (typeof item === 'string') {
          await writeText(item)
        } else {
          await writeData(item)
        }
      }
      
      controller.close()
    },
  })
}
```

--------------------------------

### Run NextJS Development Server

Source: https://github.com/run-llama/chat-ui/blob/main/examples/fastapi/README.md

Builds and runs the NextJS development server for the frontend. Access the chat UI at http://localhost:3000.

```bash
pnpm dev
```

--------------------------------

### Basic ChatSection Integration Example

Source: https://github.com/run-llama/chat-ui/blob/main/packages/chat-ui/CLAUDE.md

Demonstrates how to use the ChatSection component with the useChat hook from the Vercel AI SDK. This example shows a basic setup for integrating the chat UI with a backend API.

```typescript
import { ChatSection } from '@llamaindex/chat-ui'
import { useChat } from '@ai-sdk/react'

function MyChat() {
  const handler = useChat({
    transport: new DefaultChatTransport({
      api: '/api/chat',
    }),
  })
  return <ChatSection handler={chatHandler} />
}
```

--------------------------------

### Install Python API Client

Source: https://github.com/run-llama/chat-ui/blob/main/docs/chat-ui/artifacts.mdx

Command to install the official Python SDK for interacting with the API.

```bash
pip install example-api-client
```

--------------------------------

### Environment Setup for API Key

Source: https://github.com/run-llama/chat-ui/blob/main/CLAUDE.md

Specifies the required environment variable for full functionality of the chat UI example app. It highlights the use of OPENAI_API_KEY and mentions a fallback mechanism for fake streaming when the key is not provided.

```bash
OPENAI_API_KEY=sk-...
```

--------------------------------

### Install LlamaIndex Server Package

Source: https://github.com/run-llama/chat-ui/blob/main/packages/server/README.md

Installs the LlamaIndex Server package using npm. This is the first step to setting up the server.

```bash
npm i @llamaindex/server
```

--------------------------------

### Install JavaScript/Node.js API Client

Source: https://github.com/run-llama/chat-ui/blob/main/docs/chat-ui/artifacts.mdx

Command to install the official JavaScript/Node.js SDK for interacting with the API.

```bash
npm install @example/api-client
```

--------------------------------

### Tool Definition with Zod Schemas Example

Source: https://github.com/run-llama/chat-ui/blob/main/packages/server/examples/CLAUDE.md

Shows the consistent pattern for creating tools in LlamaIndex Server, utilizing Zod schemas for parameter validation and defining the execution logic.

```typescript
tool({
  name: 'tool_name',
  description: 'Tool description',
  parameters: z.object({
    /* parameters */
  }),
  execute: params => {
    /* implementation */
  },
})
```

--------------------------------

### Install @llamaindex/llama-deploy Package

Source: https://github.com/run-llama/chat-ui/blob/main/packages/llama-deploy/README.md

Install the @llamaindex/llama-deploy package using npm. This command fetches and installs the necessary client library into your project's node_modules directory.

```bash
npm install @llamaindex/llama-deploy
```

--------------------------------

### Task Creation API

Source: https://github.com/run-llama/chat-ui/blob/main/examples/llamadeploy/chat/generic-ui/agentic-rag-llamacloud/README.md

Endpoint to create a new task for a LlamaDeploy deployment. This is the entry point for initiating a workflow execution.

```APIDOC
## POST /deployments/chat/tasks/create

### Description
Creates a new task for the specified deployment.

### Method
POST

### Endpoint
`http://localhost:4501/deployments/chat/tasks/create`

### Parameters
#### Request Body
- **input** (string) - Required - JSON string containing user message and chat history.
- **service_id** (string) - Required - The ID of the service or workflow to execute.
```

--------------------------------

### Install @llamaindex/chat-ui Package

Source: https://github.com/run-llama/chat-ui/blob/main/README.md

Install the @llamaindex/chat-ui package into your project using npm. This command downloads and installs the library and its dependencies.

```bash
npm install @llamaindex/chat-ui
```

--------------------------------

### Install LlamaIndex Chat UI with Shadcn CLI

Source: https://github.com/run-llama/chat-ui/blob/main/docs/chat-ui/index.mdx

This command installs the LlamaIndex Chat UI components into your project using the Shadcn CLI. Ensure you have Shadcn CLI installed globally.

```shell
npx shadcn@latest add https://ui.llamaindex.ai/r/chat.json
```

--------------------------------

### SDKs and Libraries

Source: https://github.com/run-llama/chat-ui/blob/main/docs/chat-ui/artifacts.mdx

Instructions and examples for integrating with the API using provided SDKs for JavaScript/Node.js and Python.

```APIDOC
## SDKs and Libraries

We provide official SDKs for popular languages:

### JavaScript/Node.js

```bash
npm install @example/api-client
```

```javascript
import { ApiClient } from '@example/api-client'

const client = new ApiClient({
  apiKey: 'your-api-key'
})

const user = await client.users.get('user_123')
console.log(user)
```

### Python

```bash
pip install example-api-client
```

```python
from example_api import ApiClient

client = ApiClient(api_key='your-api-key')
user = client.users.get('user_123')
print(user)
```
```

--------------------------------

### Example File Part (TypeScript)

Source: https://github.com/run-llama/chat-ui/blob/main/docs/chat-ui/parts.mdx

An example of a `DataPart` with the type `data-file` in TypeScript. This part is used for file attachments, including metadata such as file name, type, URL, and size.

```typescript
const filePart = {
  type: 'data-file',
  data: {
    name: 'quarterly-report.pdf',
    type: 'application/pdf',
    url: '/files/quarterly-report.pdf',
    size: 2048576 // bytes
  }
}
```

--------------------------------

### Example Source Part (TypeScript)

Source: https://github.com/run-llama/chat-ui/blob/main/docs/chat-ui/parts.mdx

An example of a `DataPart` with the type `data-sources` in TypeScript. This part is used for displaying citations and source references, including document metadata like title, author, and page number.

```typescript
const sourcesPart = {
  type: 'data-sources',
  data: {
    nodes: [
      {
        id: 'source1',
        url: '/documents/research-paper.pdf',
        metadata: {
          title: 'Machine Learning in Healthcare',
          author: 'Dr. Jane Smith',
          page_number: 15,
          section: 'Methodology'
        }
      }
    ]
  }
}
```

--------------------------------

### Example Text Part (TypeScript)

Source: https://github.com/run-llama/chat-ui/blob/main/docs/chat-ui/parts.mdx

An example of a `TextPart` in TypeScript, which contains markdown content. This part type is used for displaying formatted text, including headings, bold, italics, and code blocks.

```typescript
const textPart = {
  type: 'text',
  text: `
# Heading
This is **bold** and *italic* text.

```javascript
console.log('Hello, world!')
```
  `
}
```

--------------------------------

### Complete Message Structure Example (TypeScript)

Source: https://github.com/run-llama/chat-ui/blob/main/docs/chat-ui/parts.mdx

Illustrates the structure of a complete message object, including various types of parts like text, data-artifact, data-sources, and data-suggested_questions. This example showcases how different data can be organized within a single message.

```typescript
const message = {
  id: 'msg-123',
  role: 'assistant',
  parts: [
    {
      type: 'text',
      text: 'I\'ve analyzed your data and here are the results:'
    },
    {
      type: 'data-artifact',
      data: {
        type: 'code',
        data: {
          title: 'Sales Analysis',
          file_name: 'analysis.py',
          language: 'python',
          code: 'import pandas as pd\n# Analysis code...'
        }
      }
    },
    {
      type: 'data-sources',
      data: {
        nodes: [
          {
            id: '1',
            url: '/data/sales.csv',
            metadata: { title: 'Sales Data Q4 2024' }
          }
        ]
      }
    },
    {
      type: 'data-suggested_questions',
      data: [
        'Can you explain the quarterly trends?',
        'What about the seasonal patterns?',
        'How can we improve performance?'
      ]
    }
  ]
}
```

--------------------------------

### Create Next.js Chat API Route

Source: https://github.com/run-llama/chat-ui/blob/main/docs/chat-ui/getting-started.mdx

Set up a Next.js API route to handle chat requests. This example demonstrates receiving JSON messages and returning a streaming response in the LlamaIndex format.

```typescript
// app/api/chat/route.ts
import { NextResponse } from 'next/server'

export async function POST(request: Request) {
  const { messages } = await request.json()

  // Your LlamaIndex chat logic here
  const response = await generateChatResponse(messages)

  // Return streaming response in LlamaIndex format
  return new Response(response, {
    headers: {
      'Content-Type': 'text/event-stream',
      'Connection': 'keep-alive',
    },
  })
}
```

--------------------------------

### Custom Chat Layout with Manual Composition

Source: https://github.com/run-llama/chat-ui/blob/main/docs/chat-ui/getting-started.mdx

Provides an example of achieving a custom layout by manually composing `ChatSection` with its child components and applying specific Tailwind CSS classes for arrangement, such as a two-column layout with `flex-row` and `gap-4`.

```tsx
import {
  ChatSection,
  ChatMessages,
  ChatInput,
  ChatCanvas,
} from '@llamaindex/chat-ui'
import { useChat } from '@ai-sdk/react'
import { DefaultChatTransport } from '@ai-sdk/react'

function CustomChat() {
  const handler = useChat({
    transport: new DefaultChatTransport({
      api: '/api/chat',
    }),
  })

  return (
    <ChatSection handler={handler} className="flex-row gap-4">
      <div className="flex-1">
        <ChatMessages />
        <ChatInput />
      </div>
      <ChatCanvas className="w-1/3" />
    </ChatSection>
  )
}
```

--------------------------------

### Configure Starter Questions in .env File

Source: https://github.com/run-llama/chat-ui/blob/main/packages/server/next/README.md

Demonstrates how to configure the initial questions displayed in the chat interface by modifying the NEXT_PUBLIC_STARTER_QUESTIONS variable in the .env file. This configuration affects the application's behavior.

```env
NEXT_PUBLIC_STARTER_QUESTIONS=['What is the capital of France?']
```

--------------------------------

### ChatMessages.Empty Example - TypeScript

Source: https://github.com/run-llama/chat-ui/blob/main/docs/chat-ui/core-components.mdx

Shows the usage of the `ChatMessages.Empty` sub-component, which is displayed when there are no messages in the chat. It allows for customizable headings and subheadings to guide new users.

```tsx
<ChatMessages.Empty
  heading="Welcome to Chat"
  subheading="Start a conversation by typing below"
/>
```

--------------------------------

### Extract Artifacts from ServerMessage - TypeScript

Source: https://github.com/run-llama/chat-ui/blob/main/packages/server/README.md

Provides examples of extracting artifacts from 'ServerMessage' instances. It demonstrates how to get all artifacts, the last artifact of any type, and the last artifact of a specific type (code or document).

```typescript
// Get all artifacts from all messages
const artifacts = serverMessages.flatMap(message => message.artifacts)

// Get the last artifact of any type
const lastArtifact = artifacts[artifacts.length - 1]

// Get the last artifact of a specific type
const lastCodeArtifact = serverMessage.getLastArtifact('code')
const lastDocumentArtifact = serverMessage.getLastArtifact('document')

```

--------------------------------

### Initialize Chat with Initial Messages

Source: https://github.com/run-llama/chat-ui/blob/main/docs/chat-ui/getting-started.mdx

Demonstrates how to provide initial messages to the chat interface when it loads. This can be used for setting context, displaying welcome messages, or pre-populating the conversation history.

```tsx
const handler = useChat({
  api: '/api/chat',
  messages: [
    {
      id: '1',
      role: 'assistant',
      content: 'Hello! How can I help you today?',
    },
  ],
})
```

--------------------------------

### Create Chat Component with useChat Hook

Source: https://github.com/run-llama/chat-ui/blob/main/docs/chat-ui/getting-started.mdx

This snippet demonstrates the basic integration of the `ChatSection` component with the `useChat` hook from `@ai-sdk/react`. It shows how to configure the chat API endpoint using `DefaultChatTransport`.

```tsx
'use client'

import { ChatSection } from '@llamaindex/chat-ui'
import { useChat } from '@ai-sdk/react'
import { DefaultChatTransport } from '@ai-sdk/react'

export default function Chat() {
  const handler = useChat({
    // use transport to specify the chat API endpoint
    // https://ai-sdk.dev/docs/migration-guides/migration-guide-5-0#chat-transport-architecture
    transport: new DefaultChatTransport({
      api: '/api/chat',
    }),
  })

  return (
    <div className="h-screen">
      <ChatSection handler={handler} />
    </div>
  )
}
```

--------------------------------

### Generate Document Embeddings

Source: https://github.com/run-llama/chat-ui/blob/main/examples/llamadeploy/chat/generic-ui/agentic-rag-llamacloud/README.md

Generates embeddings for documents located in the './ui/data' directory using the LlamaDeploy CLI. This step is crucial for the RAG functionality, as it prepares the data for efficient retrieval by the agent.

```bash
uv run generate
```

--------------------------------

### Configure Tailwind CSS for LlamaIndex Chat UI (v3.x)

Source: https://github.com/run-llama/chat-ui/blob/main/docs/chat-ui/getting-started.mdx

Add the LlamaIndex Chat UI component paths to the `content` array in your `tailwind.config.ts` file for Tailwind CSS version 3.x.

```javascript
module.exports = {
  content: [
    './app/**/*.{js,ts,jsx,tsx}',
    './node_modules/@llamaindex/chat-ui/**/*.{ts,tsx}',
  ],
  // ... rest of config
}
```

--------------------------------

### Initialize and Use JavaScript/Node.js API Client

Source: https://github.com/run-llama/chat-ui/blob/main/docs/chat-ui/artifacts.mdx

Example of initializing the JavaScript/Node.js API client with an API key and fetching user data.

```javascript
import { ApiClient } from '@example/api-client'

const client = new ApiClient({
  apiKey: 'your-api-key'
})

const user = await client.users.get('user_123')
console.log(user)
```

--------------------------------

### Import LlamaIndex Chat UI Styles

Source: https://github.com/run-llama/chat-ui/blob/main/docs/chat-ui/getting-started.mdx

Import the necessary CSS files for LlamaIndex Chat UI in your application's root file to apply styling for markdown, PDFs, and the document editor.

```tsx
import '@llamaindex/chat-ui/styles/markdown.css'
import '@llamaindex/chat-ui/styles/pdf.css'
import '@llamaindex/chat-ui/styles/editor.css'
```

--------------------------------

### Initialize and Use Python API Client

Source: https://github.com/run-llama/chat-ui/blob/main/docs/chat-ui/artifacts.mdx

Example of initializing the Python API client with an API key and fetching user data.

```python
from example_api import ApiClient

client = ApiClient(api_key='your-api-key')
user = client.users.get('user_123')
print(user)
```

--------------------------------

### Deploy Chat Workflow with llamactl

Source: https://github.com/run-llama/chat-ui/blob/main/examples/llamadeploy/chat/custom-ui/README.md

Deploys a chat workflow using the LlamaDeploy CLI (llamactl). This command registers the workflow with the API server, making it accessible through the UI.

```bash
uv run llamactl deploy llama_deploy.yml
```

--------------------------------

### Define Chat UI Theme Variables in globals.css

Source: https://github.com/run-llama/chat-ui/blob/main/docs/chat-ui/getting-started.mdx

Define theme variables (CSS custom properties) in your `app/globals.css` file for colors, typography, and spacing to customize LlamaIndex Chat UI. This step can be skipped if you already have a shadcn/ui theme set up.

```css
@import 'tailwindcss';
@source '../node_modules/@llamaindex/chat-ui/**/*.{ts,tsx}';

:root {
  /* Theme variables - see sample file for complete configuration */
  --background: oklch(1 0 0);
  --foreground: oklch(0.14 0 285.86);
  /* ... other theme variables ... */
}

.dark {
  /* Dark mode theme variables */
  --background: oklch(0.14 0 285.86);
  --foreground: oklch(0.99 0 0);
  /* ... other dark theme variables ... */
}

@theme inline {
  /* Theme mapping for Tailwind CSS */
  --color-background: var(--background);
  --color-foreground: var(--foreground);
  /* ... other color mappings ... */
}
```

--------------------------------

### Set OpenAI API Key (Bash)

Source: https://github.com/run-llama/chat-ui/blob/main/examples/nextjs/README.md

Sets the OpenAI API key as an environment variable for authentication with OpenAI services.

```bash
export OPENAI_API_KEY=your-api-key-here
```

--------------------------------

### Resume Existing Workflow Task with useWorkflow

Source: https://github.com/run-llama/chat-ui/blob/main/docs/chat-ui/hooks.mdx

This example shows how to use the useWorkflow hook to resume a previously started workflow task by providing an existing `runId`. The hook automatically fetches historical events for the specified run ID, which are then accessible via the `events` property.

```tsx
import { useWorkflow } from '@llamaindex/chat-ui'
import { useEffect } from 'react'

function ResumeWorkflowComponent() {
  const workflow = useWorkflow({
    deployment: 'my-deployment',
    runId: 'existing-run-id', // Resume existing task
    onStopEvent: event => {
      console.log('Workflow completed:', event)
    },
  })

  // Events from the existing task will be automatically fetched
  useEffect(() => {
    console.log('Restored events:', workflow.events)
  }, [workflow.events])

  return (
    <div>
      <p>Resumed run: {workflow.runId}</p>
      <p>Events: {workflow.events.length}</p>
    </div>
  )
}
```

--------------------------------

### Define Artifact Event with TypeScript

Source: https://github.com/run-llama/chat-ui/blob/main/packages/server/README.md

Defines a typed artifact event using `workflowEvent` from `@llamaindex/workflow`. This example shows how to structure an event for a 'document' artifact, including its type, creation timestamp, and specific data such as title, content, and format. The top-level event type must start with 'data-'.

```typescript
import { workflowEvent } from '@llamaindex/workflow'

// Example for a document artifact
const artifactEvent = workflowEvent<{
  type: 'data-artifact' // Must start with "data-"
  data: {
    type: 'document' // Custom type for your artifact (e.g., "document", "code")
    created_at: number
    data: {
      // Specific data for the document artifact type
      title: string
      content: string
      type: 'markdown' | 'html' // document format
    }
  }
}>()
```

--------------------------------

### Task Event Streaming API

Source: https://github.com/run-llama/chat-ui/blob/main/examples/llamadeploy/chat/generic-ui/agentic-rag-llamacloud/README.md

Endpoint to stream events related to a running task. This allows for real-time monitoring of task progress and output.

```APIDOC
## GET /deployments/chat/tasks/{TASK_ID}/events

### Description
Streams events for a given task. This is useful for observing the task's execution in real-time.

### Method
GET

### Endpoint
`http://localhost:4501/deployments/chat/tasks/$TASK_ID/events`

### Parameters
#### Path Parameters
- **TASK_ID** (string) - Required - The ID of the task to stream events from.

#### Query Parameters
- **session_id** (string) - Required - The session ID for the event stream.
- **raw_event** (boolean) - Optional - If true, returns raw event data.
```

--------------------------------

### Basic Canvas Setup with Chat UI (React)

Source: https://github.com/run-llama/chat-ui/blob/main/docs/chat-ui/artifacts.mdx

Demonstrates how to set up a basic chat interface using the ChatSection, ChatCanvas, ChatMessages, and ChatInput components from '@llamaindex/chat-ui'.

```tsx
import { ChatSection, ChatCanvas } from '@llamaindex/chat-ui'

function ChatWithCanvas() {
  const handler = useChat({
    transport: new DefaultChatTransport({
      api: '/api/chat',
    }),
  })

  return (
    <ChatSection handler={handler} className="flex h-full">
      <div className="flex-1">
        <ChatMessages />
        <ChatInput />
      </div>
      <ChatCanvas className="w-1/2 border-l" />
    </ChatSection>
  )
}
```

--------------------------------

### Create Chat Task via API

Source: https://github.com/run-llama/chat-ui/blob/main/examples/llamadeploy/chat/generic-ui/agentic-rag-llamacloud/README.md

Creates a new task for the chat deployment using a `curl` command. This endpoint is used to send user messages and chat history to the deployed workflow, initiating a conversation.

```bash
curl -X POST 'http://localhost:4501/deployments/chat/tasks/create' \
  -H 'Content-Type: application/json' \
  -d '{
    "input": "{\"user_msg\":\"Hello\",\"chat_history\":[]}",
    "service_id": "workflow"
  }'
```

--------------------------------

### Display Initial Conversation Starters (React)

Source: https://github.com/run-llama/chat-ui/blob/main/docs/chat-ui/widgets.mdx

The StarterQuestions component displays initial conversation prompts for empty chat states. It takes an array of question strings and an 'onQuestionSelect' callback to handle user interaction. This helps users start conversations easily.

```tsx
import { StarterQuestions } from '@llamaindex/chat-ui/widgets'

const starterQuestions = [
  'How can I improve my code?',
  'Explain machine learning concepts',
  'Help me debug this error',
  'What are best practices for React?',
]

function ChatStarters() {
  return (
    <StarterQuestions
      questions={starterQuestions}
      onQuestionSelect={handleQuestionSelect}
    />
  )
}
```