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

npm install copilotkit-ec-components
# or
yarn add copilotkit-ec-components
# or
pnpm add copilotkit-ec-components

Usage

Import Components

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

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

Basic Example

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 (
    <div>
      <ProductCard product={product} />
      <Button variant="primary" onClick={() => console.log('Clicked!')}>
        Add to Cart
      </Button>
    </div>
  );
}

Available Components

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 组件详细用法

ShoppingChatPage - 完整聊天页面

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

基础用法

'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 (
    <CopilotKit runtimeUrl="/api/copilotkit">
      <ShoppingChatPage />
    </CopilotKit>
  );
}

完整配置示例

'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 (
    <CopilotKit runtimeUrl="/api/copilotkit">
      <ShoppingChatPage
        // 主题颜色
        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"
      />
    </CopilotKit>
  );
}

Props 说明

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

CustomInput - 自定义输入框

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

基础用法

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

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

特性

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

图片上传流程

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

CustomUserMessage - 用户消息组件

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

基础用法

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

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

特性

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

ImagePreview - 图片预览组件

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

基础用法

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

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

Props

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

🔧 配置 CopilotKit API

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

创建 API 路由

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

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);
};

环境变量配置

创建 .env.local:

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

📦 完整示例项目

项目结构

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

完整页面示例

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

样式配置

在 app/globals.css 中添加：

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

body {
  overflow: hidden;
}

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

🎨 样式自定义

修改主题颜色

<ShoppingChatPage themeColor="#ff6b6b" />

使用 CSS 变量

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

覆盖组件样式

/* 自定义聊天容器 */
.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:

{
  "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

Building the Package

# Install dependencies
pnpm install

# Build the library
pnpm run build:lib

# Test the package
npm pack --dry-run

Publishing to npm

# Login to npm
npm login

# Publish the package
npm publish

# Or publish with a specific tag
npm publish --tag beta

Version Management

# Patch version
npm version patch

# Minor version
npm version minor

# Major version
npm version major

Project Structure

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:

# 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:

echo 'OPENAI_API_KEY=your-openai-api-key-here' > agent/.env

3. Start the development server:

# 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

Agent Connection Issues

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

Python Dependencies

If you encounter Python import errors:

npm install:agent