CopilotKit EC Components

A React component library for e-commerce applications, built with CopilotKit and LangGraph. This package provides reusable UI components and hooks for building modern e-commerce interfaces.

Features

- 🎨 Modern UI components with Tailwind CSS
- 🛒 E-commerce specific components (ProductCard, ProductList, etc.)
- 💬 CopilotKit chat integration
- 📱 Responsive design
- 🔧 TypeScript support
- 🎯 Easy to use and customize

Installation

``bash
npm install copilotkit-ec-components


or

yarn add copilotkit-ec-components

or

pnpm add copilotkit-ec-components
`

Usage

$3

`jsx
import {
ProductCard,
ProductList,
Button,
CustomInput,
CustomUserMessage
} from 'copilotkit-ec-components';

// Import styles
import 'copilotkit-ec-components/styles';
`

$3

`jsx
import React from 'react';
import { ProductCard, Button } from 'copilotkit-ec-components';
import 'copilotkit-ec-components/styles';

function App() {
const product = {
id: '1',
name: 'Sample Product',
price: 29.99,
image: '/product-image.jpg',
description: 'A great product for your needs'
};

return (



);
}
`

$3

#### UI Components
- Button - Customizable button component
- Card, CardHeader, CardContent, CardFooter, CardTitle, CardDescription - Card layout components
- Input - Input field component
- Label - Label component
- Form, FormField, FormItem, FormLabel, FormControl, FormDescription, FormMessage - Form components
- Sheet, SheetContent, SheetHeader, SheetTitle, SheetTrigger - Sheet/drawer components

#### Product Components
- ProductCard - Product display card
- ProductCardCompact - Compact product card
- ProductList - Product list container
- ProductDetailSheet - Product detail modal/sheet

#### Chat Components
- ShoppingChatPage - 完整的电商AI聊天页面组件
- CustomInput - 自定义聊天输入框
- CustomUserMessage - 自定义用户消息显示
- ImagePreview - 图片预览组件

#### Utilities
- cn - Utility function for combining CSS classes

---

💬 Chat 组件详细用法

$3

ShoppingChatPage 是一个开箱即用的完整电商AI聊天页面组件，集成了商品搜索、图片上传、消息展示等功能。

#### 基础用法

`tsx
'use client';

import { CopilotKit } from '@copilotkit/react-core';
import { ShoppingChatPage } from 'copilotkit-ec-components';
import 'copilotkit-ec-components/styles';
import '@copilotkit/react-ui/styles.css';

export default function ChatPage() {
return (



);
}
`

#### 完整配置示例

`tsx
'use client';

import { CopilotKit } from '@copilotkit/react-core';
import { ShoppingChatPage } from 'copilotkit-ec-components';
import 'copilotkit-ec-components/styles';
import '@copilotkit/react-ui/styles.css';

export default function ChatPage() {
return (

// 主题颜色
themeColor="#6366f1"

// AI助手的指令
instructions="你是一个电商购物助手。根据用户的问题，搜索商品并生成购物报告。"

// 标签配置
labels={{
title: "AI 购物助手",
initial: "👋 你好！我是你的 AI 购物助手，专门帮助你找到心仪的商品。\n\n我可以帮你：\n- 搜索商品\n- 上传图片搜索\n- 商品对比分析"
}}

// 快捷建议
suggestions={[
{
title: "零食好物",
message: "我想买一些零食好物，推荐一些适合的商品",
},
{
title: "蓝牙鼠标",
message: "我想买蓝牙鼠标",
},
{
title: "女装上衣",
message: "我想给女朋友买一件女装上衣",
},
]}

// 自定义 CSS 类名
className="custom-chat-page"
/>

);
}
`

#### Props 说明

| 属性 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| themeColor | string | "#6366f1" | 主题颜色（十六进制） |
| instructions | string | 预设指令 | AI助手的行为指令 |
| labels | object | 预设标签 | 聊天界面的标题和欢迎消息 |
| labels.title | string | "AI 购物助手" | 聊天标题 |
| labels.initial | string | 预设欢迎消息 | 初始欢迎消息 |
| suggestions | array | 预设建议 | 快捷建议按钮配置 |
| className | string | "" | 自定义 CSS 类名 |

---

$3

CustomInput 是一个支持文本输入和图片上传的聊天输入组件。

#### 基础用法

`tsx
import { CopilotChat } from '@copilotkit/react-ui';
import { CustomInput } from 'copilotkit-ec-components';

Input={CustomInput}
// ... 其他配置
/>
`

#### 特性

- ✅ 支持文本输入
- ✅ 支持图片上传（点击图标或拖拽）
- ✅ 图片预览功能
- ✅ 上传进度显示
- ✅ 图片识别和搜索

#### 图片上传流程

1. 点击图片图标或拖拽图片到输入框
2. 自动上传图片到服务器
3. 显示上传进度
4. 上传成功后显示预览
5. AI根据图片内容推荐商品

---

$3

CustomUserMessage 用于展示用户发送的消息，支持文本和图片消息。

#### 基础用法

`tsx
import { CopilotChat } from '@copilotkit/react-ui';
import { CustomUserMessage } from 'copilotkit-ec-components';

UserMessage={CustomUserMessage}
// ... 其他配置
/>
`

#### 特性

- ✅ 显示用户头像
- ✅ 支持文本消息
- ✅ 支持图片消息预览
- ✅ 显示发送时间
- ✅ 响应式布局

---

$3

ImagePreview 用于在聊天中预览上传的图片。

#### 基础用法

`tsx
import { ImagePreview } from 'copilotkit-ec-components';

imageUrl="https://example.com/image.jpg"
onRemove={() => console.log('Remove image')}
/>
`

#### Props

| 属性 | 类型 | 必填 | 说明 |
|------|------|------|------|
| imageUrl | string | ✅ | 图片 URL |
| onRemove | () => void | ❌ | 删除图片的回调函数 |

---

🔧 配置 CopilotKit API

使用 Chat 组件需要配置 CopilotKit API 路由。

$3

创建 app/api/copilotkit/route.ts:

`typescript
import {
CopilotRuntime,
ExperimentalEmptyAdapter,
copilotRuntimeNextJSAppRouterEndpoint,
} from "@copilotkit/runtime";
import { LangGraphAgent } from "@ag-ui/langgraph";
import { NextRequest } from "next/server";

const serviceAdapter = new ExperimentalEmptyAdapter();

const runtime = new CopilotRuntime({
agents: {
"sample_agent": new LangGraphAgent({
deploymentUrl: process.env.LANGGRAPH_DEPLOYMENT_URL || "your-deployment-url",
graphId: "sample_agent",
langsmithApiKey: process.env.LANGSMITH_API_KEY || "",
}),
}
});

export const POST = async (req: NextRequest) => {
const { handleRequest } = copilotRuntimeNextJSAppRouterEndpoint({
runtime,
serviceAdapter,
endpoint: "/api/copilotkit",
});

return handleRequest(req);
};
`

$3

创建 .env.local:

`bash
LANGGRAPH_DEPLOYMENT_URL=your-deployment-url
LANGSMITH_API_KEY=your-api-key
`

---

📦 完整示例项目

$3

`
my-shopping-app/
├── app/
│ ├── api/
│ │ └── copilotkit/
│ │ └── route.ts # CopilotKit API 路由
│ ├── chat/
│ │ └── page.tsx # 聊天页面
│ ├── layout.tsx
│ └── globals.css
├── package.json
└── .env.local
`

$3

`tsx
// app/chat/page.tsx
'use client';

import { CopilotKit } from '@copilotkit/react-core';
import { ShoppingChatPage } from 'copilotkit-ec-components';
import 'copilotkit-ec-components/styles';
import '@copilotkit/react-ui/styles.css';

export default function ChatPage() {
return (

themeColor="#6366f1"
instructions="你是一个专业的电商购物助手，帮助用户找到心仪的商品。"
labels={{
title: "AI 购物助手",
initial: "👋 你好！我可以帮你搜索商品、分析价格、推荐好物。\n\n直接告诉我你想买什么，或者上传商品图片，我来帮你找！"
}}
suggestions={[
{ title: "数码产品", message: "推荐一些性价比高的数码产品" },
{ title: "家居好物", message: "有什么实用的家居好物推荐吗" },
{ title: "美妆护肤", message: "最近有什么热门的美妆产品" },
]}
/>

);
}
`

$3

在 app/globals.css 中添加：

`css
html,
body {
height: 100%;
margin: 0;
padding: 0;
}

body {
overflow: hidden;
}

/ 自定义聊天样式 /
.custom-chat-page {
/ 你的自定义样式 /
}
`

---

🎨 样式自定义

$3

`tsx

`

$3

`css
:root {
--copilot-kit-primary-color: #6366f1;
--copilot-kit-background: #ffffff;
--copilot-kit-text: #000000;
}
`

$3

`css
/ 自定义聊天容器 /
.copilotKitChat {
border-radius: 12px;
box-shadow: 0 4px 6px rgba(0, 0, 0, 0.1);
}

/ 自定义输入框 /
.copilotKitInput {
background: #f5f5f5;
border-radius: 8px;
}

/ 自定义消息气泡 /
.copilotKitMessages {
padding: 20px;
}
`

Peer Dependencies

This package requires the following peer dependencies:

`json
{
"react": "^18.0.0 || ^19.0.0",
"react-dom": "^18.0.0 || ^19.0.0",
"next": "^13.0.0 || ^14.0.0 || ^15.0.0 || ^16.0.0"
}
`

Development

$3

`bash


Install dependencies

pnpm install

Build the library

pnpm run build:lib

Test the package

npm pack --dry-run
`

$3

`bash


Login to npm

npm login

Publish the package

npm publish

Or publish with a specific tag

npm publish --tag beta
`

$3

`bash


Patch version

npm version patch

Minor version

npm version minor

Major version

npm version major
`

$3

`
src/
├── components/
│ ├── ui/ # Base UI components
│ ├── products/ # E-commerce components
│ └── chat/ # Chat/AI components
├── lib/
│ ├── utils.ts # Utility functions
│ └── api/ # API utilities
├── hooks/ # Custom hooks
└── types/ # TypeScript definitions
`

Prerequisites

- Node.js 18+
- Python 3.8+
- Any of the following package managers:
- pnpm (recommended)
- npm
- yarn
- bun
- OpenAI API Key (for the LangGraph agent)

> Note: This repository ignores lock files (package-lock.json, yarn.lock, pnpm-lock.yaml, bun.lockb) to avoid conflicts between different package managers. Each developer should generate their own lock file using their preferred package manager. After that, make sure to delete it from the .gitignore.

Getting Started

1. Install dependencies using your preferred package manager:
`bash


Using pnpm (recommended)

pnpm install

Using npm

npm install

Using yarn

yarn install

Using bun

bun install
`

> Note: Installing the package dependencies will also install the agent's python dependencies via the install:agent script.


2. Set up your OpenAI API key:
`bash
echo 'OPENAI_API_KEY=your-openai-api-key-here' > agent/.env
`

3. Start the development server:
`bash


Using pnpm

pnpm dev

Using npm

npm run dev

Using yarn

yarn dev

Using bun

bun run dev
`

This will start both the UI and agent servers concurrently.

Available Scripts

The following scripts can also be run using your preferred package manager:
- dev - Starts both UI and agent servers in development mode
- dev:debug - Starts development servers with debug logging enabled
- dev:ui - Starts only the Next.js UI server
- dev:agent - Starts only the LangGraph agent server
- build - Builds the Next.js application for production
- start - Starts the production server
- lint - Runs ESLint for code linting
- install:agent - Installs Python dependencies for the agent

Documentation

The main UI component is in src/app/page.tsx. You can:
- Modify the theme colors and styling
- Add new frontend actions
- Customize the CopilotKit sidebar appearance

📚 Documentation

- LangGraph Documentation - Learn more about LangGraph and its features
- CopilotKit Documentation - Explore CopilotKit's capabilities
- Next.js Documentation - Learn about Next.js features and API
- YFinance Documentation - Financial data tools

Contributing

Feel free to submit issues and enhancement requests! This starter is designed to be easily extensible.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Troubleshooting

$3

If you see "I'm having trouble connecting to my tools", make sure:
1. The LangGraph agent is running on port 8000
2. Your OpenAI API key is set correctly
3. Both servers started successfully

$3

If you encounter Python import errors:
`bash
npm install:agent
``