CLI

创建一个新的 ChatJS 应用：

npx @chat-js/cli@latest create my-app

CLI 会引导你完成网关、功能和认证选项的选择，生成 chat.config.ts 文件，并列出你所选配置所需的环境变量。

功能特性

• 120+ 模型：通过一个 API 即可调用 Claude、GPT、Gemini、Grok 等多种模型。
• 认证：支持 GitHub、Google 和匿名登录，开箱即用。
• 附件支持：图片、PDF、文档等，支持拖放上传。
• 断点续传流：页面刷新后仍可继续生成内容。
• 分支对话：复制并扩展对话，探索不同可能性。
• 分享功能：通过公开链接分享对话记录。
• 网络搜索：实时集成网页搜索功能。
• 图像生成：基于 AI 的图像创作能力。
• 代码执行：在沙盒环境中运行代码片段。
• MCP：支持模型上下文协议。
• 桌面应用：使用 Electron 将应用打包为原生 macOS、Windows 或 Linux 应用。

技术栈

• Next.js - App Router、React Server Components
• TypeScript - 完整的类型安全支持
• AI SDK - 面向 TypeScript 的 AI 工具包
• AI Gateway - 统一接入 120+ 种 AI 模型
• Better Auth - 身份验证与授权服务
• Drizzle ORM - 类型安全的数据库查询
• PostgreSQL - 主数据库
• Redis - 缓存与断点续传流支持
• Vercel Blob - 对象存储
• Shadcn/UI - 美观且易访问的组件库
• Tailwind CSS - 样式化工具
• tRPC - 端到端类型安全的 API
• Zod - 数据模式验证
• Zustand - 状态管理
• Motion - 动画效果
• t3-env - 环境变量管理
• Pino - 结构化日志记录
• Langfuse - LLM 可观测性与分析
• Vercel Analytics - 网站分析
• Biome - 代码检查与格式化工具
• Ultracite - Biome 预设，适合人类与 AI 共同使用
• Streamdown - 专为 AI 流式传输设计的 Markdown 格式
• AI Elements - 原生 AI 组件
• AI SDK Tools - 面向 AI SDK 的开发者工具

单仓库布局

• apps/site: 登录页 (chatjs.dev)
• apps/chat: Next.js 聊天应用 (demo.chatjs.dev)
• apps/docs: Mintlify 文档 (chatjs.dev/docs)
• packages/cli: 交互式脚手架 CLI

开发

• bun dev:chat: 运行聊天应用
• bun dev:docs: 运行文档
• bun lint: 运行工作区代码检查
• bun test:types: 运行聊天应用的类型检查

发布流程

发布由 Changesets 驱动，适用于整个代码库。

• 每当你修改可发布的包时，添加一个 changeset。
• 合并 Changesets 工作流自动生成的版本 PR。
• 公开的包（如 @chat-js/cli）会发布到 npm。
• @chat-js/electron 的桌面安装包则发布到 GitHub Releases。

许可证

Apache-2.0

ChatJS 快速上手指南

ChatJS 是一个生产就绪的 AI 聊天应用基础架构，内置身份验证、支持 120+ 模型、流式传输及多种工具，帮助开发者快速构建独特的 AI 应用。

环境准备

在开始之前，请确保你的开发环境满足以下要求：

• 操作系统：macOS, Windows, 或 Linux
• Node.js：建议安装最新 LTS 版本 (推荐配合 bun 使用以获得最佳体验)
• 包管理器：推荐使用 bun (项目原生支持)，也可使用 npm 或 pnpm
• 数据库：PostgreSQL (用于主数据存储)
• 缓存：Redis (用于缓存和可恢复的流式传输)
• 账号准备：
  • Vercel 账号 (用于部署和 AI Gateway)
  • 数据库托管服务 (如 Neon, Supabase 或本地 PG)
  • Redis 托管服务 (如 Upstash 或本地 Redis)

国内开发者提示：如果访问 npm 源较慢，建议配置淘宝镜像源：

npm config set registry https://registry.npmmirror.com

若使用 bun，可配置：

bun config set registry https://registry.npmmirror.com

安装步骤

使用官方 CLI 工具一键创建新项目。CLI 会引导你配置网关、功能模块和认证方式，并自动生成配置文件。

1. 创建应用 在终端运行以下命令（将 my-app 替换为你的项目名称）：

   npx @chat-js/cli@latest create my-app
   

2. 跟随向导配置 运行命令后，CLI 会交互式地询问以下信息：

   • AI Gateway 配置：选择模型提供商接入方式。
   • 功能选择：勾选需要的特性（如网页搜索、图片生成等）。
   • 认证方式：选择 GitHub、Google 或匿名登录。

3. 配置环境变量 项目生成后，CLI 会列出所需的环境变量。请在项目根目录创建 .env 文件，并根据提示填入以下关键信息：

   • 数据库连接字符串 (DATABASE_URL)
   • Redis 连接地址 (REDIS_URL)
   • Vercel AI Gateway Key 或直接的大模型 API Key
   • 认证相关的 Secret 和 Callback URL

基本使用

项目初始化完成后，你可以立即启动开发服务器进行预览和调试。

1. 启动开发服务器 进入项目目录，运行：

   bun dev:chat
   

   (如果你未安装 bun，可使用 npm run dev:chat 或 pnpm dev:chat)

2. 访问应用 打开浏览器访问 http://localhost:3000 (具体端口请以终端输出为准)。

3. 核心功能体验

   • 对话：直接在界面输入消息，体验支持 120+ 模型（Claude, GPT, Gemini 等）的流式对话。
   • 多模态：尝试拖拽上传图片或 PDF 文档进行分析。
   • 高级特性：测试“分支对话”(Fork) 功能探索不同回答，或使用“代码执行”沙箱运行代码片段。

4. 打包桌面应用 (可选) 如需构建原生桌面应用 (macOS/Windows/Linux)，可针对 Electron 版本进行构建：

   bun build:electron
   

现在，你已经拥有了一个功能完备的 AI 聊天应用底座，可以基于 apps/chat 目录开始定制你的独特功能了。