iblai-component

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

/iblai-component

Overview of all ibl.ai components and how to create a new app.

AI Assistant: Before adding a component or creating a new app, check for a
iblai.env
in the project root. Look for
PLATFORM
,
DOMAIN
, and
TOKEN
variables. If the file does not exist or is missing these variables, tell the user: "You need an
iblai.env
with your platform configuration. Download the template and fill in your values:
curl -o iblai.env https://raw.githubusercontent.com/iblai/vibe/refs/heads/main/iblai.env
"
iblai.env
is NOT a
.env.local
replacement — it only holds the 3 shorthand variables. Next.js still reads runtime env vars from
.env.local
.
Use
pnpm
as the default package manager. Fall back to
npm
if pnpm is not installed. The generated app should live in the current directory, not in a subdirectory.

所有 ibl.ai 组件概览以及如何创建新应用。

AI 助手： 在添加组件或创建新应用前，请检查项目根目录下是否存在
iblai.env
文件，查找其中的
PLATFORM
、
DOMAIN
和
TOKEN
变量。如果文件不存在或缺少这些变量，请告知用户： "你需要一个包含平台配置的
iblai.env
文件。下载模板并填写你的配置值：
curl -o iblai.env https://raw.githubusercontent.com/iblai/vibe/refs/heads/main/iblai.env
"
iblai.env
不是
.env.local
的替代品——它仅存储这3个简写变量。Next.js 仍然会从
.env.local
读取运行时环境变量。
请默认使用
pnpm
作为包管理器，如果未安装 pnpm 则回退到
npm
。生成的应用应该存放在当前目录下，而不是子目录中。

Creating a New App

创建新应用

Vanilla Next.js + ibl.ai Features

原生 Next.js + ibl.ai 功能

Start with a standard Next.js app and add features as needed:

The CLI reads

PLATFORM

from

iblai.env

automatically. Pass

--platform

only if you want to override it or don't have an

iblai.env

bash

npx create-next-app@latest . --yes
iblai add auth
iblai add chat
pnpm dev

从标准 Next.js 应用开始，按需添加功能：

CLI 会自动从

iblai.env

读取

PLATFORM

变量。仅当你需要覆盖该配置或没有

iblai.env

文件时，才需要传递

--platform

参数。

bash

npx create-next-app@latest . --yes
iblai add auth
iblai add chat
pnpm dev

Full ibl.ai Agent App

完整 ibl.ai Agent 应用

Scaffold a complete app with auth, chat, and everything pre-configured. Always create in a temp directory and copy back to the current directory:

bash

iblai startapp agent -o .iblai-init
cp -a .iblai-init/<app-name>/. . && rm -rf .iblai-init
cp .env.example .env.local
pnpm install && pnpm dev

搭建包含鉴权、聊天等所有预配置的完整应用。请始终先在临时目录创建，再复制回当前目录：

bash

iblai startapp agent -o .iblai-init
cp -a .iblai-init/<app-name>/. . && rm -rf .iblai-init
cp .env.example .env.local
pnpm install && pnpm dev

Non-Interactive (CI/CD)

非交互模式（CI/CD）

bash

iblai startapp agent --yes --platform acme --agent my-id --app-name my-app -o .iblai-init
cp -a .iblai-init/my-app/. . && rm -rf .iblai-init
cp .env.example .env.local

bash

iblai startapp agent --yes --platform acme --agent my-id --app-name my-app -o .iblai-init
cp -a .iblai-init/my-app/. . && rm -rf .iblai-init
cp .env.example .env.local

AI-Enhanced Scaffolding

AI 增强脚手架

Set your API key as an environment variable (never pass secrets as CLI arguments):

bash

export ANTHROPIC_API_KEY=<your-key>
iblai startapp agent \
  --prompt "kids learning assistant with bright colors"

将你的 API 密钥设置为环境变量（切勿将密钥作为 CLI 参数传递）：

bash

export ANTHROPIC_API_KEY=<your-key>
iblai startapp agent \
  --prompt "kids learning assistant with bright colors"

Available Components

可用组件

Command	What It Adds	Skill
`iblai add mcp`	MCP servers + skills (run first)
`iblai add auth`	SSO authentication	`/iblai-auth`
`iblai add chat`	AI chat widget (requires agent ID)	`/iblai-chat`
`iblai add profile`	User profile dropdown	`/iblai-profile`
`iblai add account`	Account/organization settings	`/iblai-account`
`iblai add analytics`	Analytics dashboard	`/iblai-analytics`
`iblai add notification`	Notification bell	`/iblai-notification`
	User invitation dialogs	`/iblai-invite`
	Workflow builder components	`/iblai-workflow`
`iblai add builds`	Tauri v2 desktop/mobile shell

命令	添加内容	对应 Skill
`iblai add mcp`	MCP 服务器 + skills（请优先运行）
`iblai add auth`	SSO 身份验证	`/iblai-auth`
`iblai add chat`	AI 聊天组件（需要 agent ID）	`/iblai-chat`
`iblai add profile`	用户资料下拉菜单	`/iblai-profile`
`iblai add account`	账户/组织设置	`/iblai-account`
`iblai add analytics`	数据分析看板	`/iblai-analytics`
`iblai add notification`	通知铃铛	`/iblai-notification`
	用户邀请对话框	`/iblai-invite`
	工作流构建器组件	`/iblai-workflow`
`iblai add builds`	Tauri v2 桌面/移动端外壳

Component Gallery

组件库展示

All components below are from

@iblai/iblai-js/web-containers

(v1.1.28). Use MCP tools (

get_component_info

get_hook_info

) for full props and usage examples.

Auto-generated from
@iblai/web-containers@1.1.28
type declarations. Re-generate with:
iblai update-gallery <path>

以下所有组件均来自

@iblai/iblai-js/web-containers

（v1.1.28）。使用 MCP 工具（

get_component_info

、

get_hook_info

）可查看完整属性和使用示例。

由
@iblai/web-containers@1.1.28
类型声明自动生成。可通过以下命令重新生成：
iblai update-gallery <path>

Authentication & SSO

身份验证与 SSO

Export	Import	Description
`DEFAULT_SSO_STORAGE_KEYS`	sso	Default localStorage key constants for SSO
`LoginButton`	root	Auth login button -- redirects to `authUrl` with redirect options
`SignupButton`	root	Signup button -- opens signup flow, optionally in new tab
`SsoLogin`	next	SSO callback handler -- stores tokens from URL into localStorage and redirects

typescript

import { DEFAULT_SSO_STORAGE_KEYS } from "@iblai/iblai-js/web-containers/sso";
import { LoginButton, SignupButton } from "@iblai/iblai-js/web-containers";
import { SsoLogin } from "@iblai/iblai-js/web-containers/next";

导出项	导入路径	说明
`DEFAULT_SSO_STORAGE_KEYS`	sso	SSO 使用的默认 localStorage 键常量
`LoginButton`	root	身份验证登录按钮——携带重定向参数跳转至 `authUrl`
`SignupButton`	root	注册按钮——开启注册流程，可选择在新标签页打开
`SsoLogin`	next	SSO 回调处理器——将 URL 中的令牌存入 localStorage 并执行重定向

typescript

import { DEFAULT_SSO_STORAGE_KEYS } from "@iblai/iblai-js/web-containers/sso";
import { LoginButton, SignupButton } from "@iblai/iblai-js/web-containers";
import { SsoLogin } from "@iblai/iblai-js/web-containers/next";

User Profile & Account

用户资料与账户

Export	Import	Description
`Account`	next	Account/org settings with tabs (Organization, Management, Integrations, Advanced, Billing)
`CompanyDialog`	root	Company selection dialog
`EducationDialog`	root	Dialog for adding/editing education
`EducationTab`	root	Education background management
`ExperienceDialog`	root	Dialog for adding/editing experience
`ExperienceTab`	root	Professional experience management
`InstitutionDialog`	root	Institution selection dialog
`InviteUserDialog`	root	Dialog to invite users to a tenant
`InvitedUsersDialog`	root	Dialog showing pending invitations
`LocalLLMTab`	root	Local LLM model management (Tauri desktop)
`OrganizationTab`	next	Organization settings tab
`Profile`	root	Full profile management component
`ResumeTab`	root	Resume upload and display
`UserProfileDropdown`	next	Avatar dropdown with profile, organization, tenant switcher, logout
`UserProfileModal`	next	Profile editing modal with tabs (Basic, Social, Education, Experience, Resume, Security)

typescript

import { Account, OrganizationTab, UserProfileDropdown, UserProfileModal } from "@iblai/iblai-js/web-containers/next";
import { CompanyDialog, EducationDialog, EducationTab, ExperienceDialog, ExperienceTab, InstitutionDialog, ... } from "@iblai/iblai-js/web-containers";

导出项	导入路径	说明
`Account`	next	账户/组织设置页，包含标签页（组织、管理、集成、高级设置、账单）
`CompanyDialog`	root	公司选择对话框
`EducationDialog`	root	新增/编辑教育背景对话框
`EducationTab`	root	教育背景管理页
`ExperienceDialog`	root	新增/编辑工作经历对话框
`ExperienceTab`	root	工作经历管理页
`InstitutionDialog`	root	机构选择对话框
`InviteUserDialog`	root	邀请用户加入租户的对话框
`InvitedUsersDialog`	root	展示待处理邀请的对话框
`LocalLLMTab`	root	本地 LLM 模型管理页（Tauri 桌面端）
`OrganizationTab`	next	组织设置标签页
`Profile`	root	完整的资料管理组件
`ResumeTab`	root	简历上传与展示页
`UserProfileDropdown`	next	头像下拉菜单，包含资料、组织、租户切换、登出功能
`UserProfileModal`	next	资料编辑弹窗，包含标签页（基础信息、社交账号、教育背景、工作经历、简历、安全设置）

typescript

import { Account, OrganizationTab, UserProfileDropdown, UserProfileModal } from "@iblai/iblai-js/web-containers/next";
import { CompanyDialog, EducationDialog, EducationTab, ExperienceDialog, ExperienceTab, InstitutionDialog, ... } from "@iblai/iblai-js/web-containers";

Tenant & Organization

租户与组织

Export	Import	Description
`TenantSwitcher`	root	Switch between tenants/organizations with RBAC support

typescript

import { TenantSwitcher } from "@iblai/iblai-js/web-containers";

导出项	导入路径	说明
`TenantSwitcher`	root	租户/组织切换器，支持 RBAC

typescript

import { TenantSwitcher } from "@iblai/iblai-js/web-containers";

Analytics

数据分析

Export	Import	Description
`AccessTimeHeatmap`	root	Access time heatmap visualization
`AnalyticsCourseDetail`	root	Single course detail view
`AnalyticsCourses`	root	Course analytics listing
`AnalyticsFinancialStats`	root	Financial/billing statistics
`AnalyticsLayout`	root	Layout wrapper for analytics pages
`AnalyticsOverview`	root	Overview dashboard with key metrics
`AnalyticsProgramDetail`	root	Single program detail view
`AnalyticsPrograms`	root	Program analytics listing
`AnalyticsReportDownload`	root	Download analytics reports
`AnalyticsReports`	root	Report listing and management
`AnalyticsSettingsProvider`	root	Context provider for analytics settings
`AnalyticsTopicsStats`	root	Topic/conversation statistics
`AnalyticsTranscriptsStats`	root	Transcript browsing and search
`AnalyticsUsersStats`	root	User activity statistics
`ChartCardWrapper`	root	Wrapper for chart visualizations
`ChartFiltersProvider`	root	Context provider for chart filter state
`CustomDateRangePicker`	root	Custom date range selector
`EmptyStats`	root	Empty state placeholder for stats
`GroupsFilterDropdown`	root	Filter analytics by user groups
`StatCard`	root	Single statistic card
`TimeFilter`	root	Time range filter dropdown

typescript

import { AccessTimeHeatmap, AnalyticsCourseDetail, AnalyticsCourses, AnalyticsFinancialStats, AnalyticsLayout, AnalyticsOverview, ... } from "@iblai/iblai-js/web-containers";

导出项	导入路径	说明
`AccessTimeHeatmap`	root	访问时间热力图可视化
`AnalyticsCourseDetail`	root	单门课程详情视图
`AnalyticsCourses`	root	课程数据分析列表
`AnalyticsFinancialStats`	root	财务/账单统计
`AnalyticsLayout`	root	数据分析页面布局容器
`AnalyticsOverview`	root	概览看板，展示核心指标
`AnalyticsProgramDetail`	root	单个项目详情视图
`AnalyticsPrograms`	root	项目数据分析列表
`AnalyticsReportDownload`	root	数据分析报告下载功能
`AnalyticsReports`	root	报告列表与管理页
`AnalyticsSettingsProvider`	root	数据分析设置的上下文提供者
`AnalyticsTopicsStats`	root	主题/对话统计
`AnalyticsTranscriptsStats`	root	转录内容浏览与搜索
`AnalyticsUsersStats`	root	用户活动统计
`ChartCardWrapper`	root	图表可视化容器
`ChartFiltersProvider`	root	图表筛选状态的上下文提供者
`CustomDateRangePicker`	root	自定义日期范围选择器
`EmptyStats`	root	统计数据为空的占位状态
`GroupsFilterDropdown`	root	按用户组筛选数据分析结果的下拉菜单
`StatCard`	root	单个统计指标卡片
`TimeFilter`	root	时间范围筛选下拉菜单

typescript

import { AccessTimeHeatmap, AnalyticsCourseDetail, AnalyticsCourses, AnalyticsFinancialStats, AnalyticsLayout, AnalyticsOverview, ... } from "@iblai/iblai-js/web-containers";

Notifications

通知

Export	Import	Description
`AlertsTab`	root	Alert management tab
`EditAlertDialog`	root	Dialog to create/edit alerts
`NotificationDisplay`	root	Full notification center with Inbox and Alerts tabs
`NotificationDropdown`	root	Bell icon with unread badge -- compact navbar widget
`SendNotificationDialog`	root	Dialog to compose and send notifications (admin)

typescript

import { AlertsTab, EditAlertDialog, NotificationDisplay, NotificationDropdown, SendNotificationDialog } from "@iblai/iblai-js/web-containers";

导出项	导入路径	说明
`AlertsTab`	root	告警管理标签页
`EditAlertDialog`	root	创建/编辑告警的对话框
`NotificationDisplay`	root	完整的通知中心，包含收件箱和告警标签页
`NotificationDropdown`	root	带未读角标的铃铛图标——紧凑的导航栏组件
`SendNotificationDialog`	root	撰写和发送通知的对话框（管理员用）

typescript

import { AlertsTab, EditAlertDialog, NotificationDisplay, NotificationDropdown, SendNotificationDialog } from "@iblai/iblai-js/web-containers";

Mentor UI (App Shell)

Mentor UI（应用外壳）

Export	Import	Description
`AppSidebar`	next	Collapsible sidebar with menu items, projects, pinned/recent messages
`ConversationStarters`	next	Guided prompt cards for starting conversations
`NavBar`	next	Top navigation bar with user menu, mentor dropdown, new chat action

typescript

import { AppSidebar, ConversationStarters, NavBar } from "@iblai/iblai-js/web-containers/next";

导出项	导入路径	说明
`AppSidebar`	next	可折叠侧边栏，包含菜单项、项目、置顶/最近消息
`ConversationStarters`	next	引导式提示词卡片，用于快速开启对话
`NavBar`	next	顶部导航栏，包含用户菜单、mentor 下拉菜单、新建聊天按钮

typescript

import { AppSidebar, ConversationStarters, NavBar } from "@iblai/iblai-js/web-containers/next";

Workflows

工作流

Export	Import	Description
`ConnectorManagementDialog`	root	Connector setup and management
`CreateWorkflowModal`	root	Create new workflow modal
`DeleteWorkflowModal`	root	Delete workflow confirmation
`ToolDialogs`	root	Tool configuration dialogs
`WorkflowSidebar`	root	Workflow node type browser sidebar

typescript

import { ConnectorManagementDialog, CreateWorkflowModal, DeleteWorkflowModal, ToolDialogs, WorkflowSidebar } from "@iblai/iblai-js/web-containers";

导出项	导入路径	说明
`ConnectorManagementDialog`	root	连接器设置与管理对话框
`CreateWorkflowModal`	root	创建新工作流的弹窗
`DeleteWorkflowModal`	root	删除工作流的确认弹窗
`ToolDialogs`	root	工具配置对话框集合
`WorkflowSidebar`	root	工作流节点类型浏览侧边栏

typescript

import { ConnectorManagementDialog, CreateWorkflowModal, DeleteWorkflowModal, ToolDialogs, WorkflowSidebar } from "@iblai/iblai-js/web-containers";

Content & Display

内容与展示

Export	Import	Description
`CopyButtonIcon`	root	Copy-to-clipboard button icon
`Loader`	root	Loading overlay component
`Markdown`	root	Markdown renderer with syntax highlighting and copy buttons
`RichTextEditor`	root	Tiptap-based rich text editor (HTML or Markdown output)
`SearchableMultiSelect`	root	Multi-select dropdown with search filtering
`Spinner`	root	Loading spinner (sm, md, lg)
`TimeTrackingProvider`	root	Provider for automatic time tracking
`TopBanner`	root	Dismissible top banner notification bar
`Version`	root	App version display footer

typescript

import { CopyButtonIcon, Loader, Markdown, RichTextEditor, SearchableMultiSelect, Spinner, ... } from "@iblai/iblai-js/web-containers";

导出项	导入路径	说明
`CopyButtonIcon`	root	复制到剪贴板按钮图标
`Loader`	root	加载遮罩组件
`Markdown`	root	Markdown 渲染器，支持语法高亮和复制按钮
`RichTextEditor`	root	基于 Tiptap 的富文本编辑器（支持输出 HTML 或 Markdown）
`SearchableMultiSelect`	root	支持搜索筛选的多选下拉菜单
`Spinner`	root	加载动画（支持 sm, md, lg 三种尺寸）
`TimeTrackingProvider`	root	自动时间追踪功能的提供者
`TopBanner`	root	可关闭的顶部通知栏
`Version`	root	应用版本展示页脚

typescript

import { CopyButtonIcon, Loader, Markdown, RichTextEditor, SearchableMultiSelect, Spinner, ... } from "@iblai/iblai-js/web-containers";

Error Handling

错误处理

Export	Import	Description
`ClientErrorPage`	next	Client-side error boundary page
`ErrorPage`	next	Error page with code, message, support link, home button

typescript

import { ClientErrorPage, ErrorPage } from "@iblai/iblai-js/web-containers/next";

导出项	导入路径	说明
`ClientErrorPage`	next	客户端错误边界页面
`ErrorPage`	next	错误页面，包含错误码、错误信息、支持链接、返回首页按钮

typescript

import { ClientErrorPage, ErrorPage } from "@iblai/iblai-js/web-containers/next";

Hooks & Utilities

Hooks 与工具函数

Export	Import	Description
`TAURI_COMMANDS`	root	Tauri IPC command name constants
`TAURI_EVENTS`	root	Tauri event name constants

typescript

import { TAURI_COMMANDS, TAURI_EVENTS } from "@iblai/iblai-js/web-containers";

导出项	导入路径	说明
`TAURI_COMMANDS`	root	Tauri IPC 命令名常量
`TAURI_EVENTS`	root	Tauri 事件名常量

typescript

import { TAURI_COMMANDS, TAURI_EVENTS } from "@iblai/iblai-js/web-containers";

UI Primitives (Shadcn/Radix)

UI 基础组件（Shadcn/Radix）

These are bundled with the SDK and share the ibl.ai Tailwind theme. Available when you need lower-level building blocks inside SDK component customizations:

AlertDialog

Avatar

Badge

Button

Calendar

Card

CardContent

CardDescription

CardFooter

CardHeader

CardTitle

Chart

Checkbox

Dialog

DropdownMenu

Input

Label

Pagination

Popover

Progress

RadioGroup

Select

Separator

Sheet

Sidebar

Skeleton

Sonner

Switch

Table

Tabs

Textarea

Toast

Toaster

Toggle

Tooltip

Note: For your own UI, install shadcn/ui directly (
npx shadcn@latest add ...
) rather than importing these from the SDK. The SDK exports are for internal use and SDK component customization.

这些组件与 SDK 打包在一起，共享 ibl.ai 的 Tailwind 主题。当你在自定义 SDK 组件需要更低层级的构建块时可以使用：

AlertDialog

Avatar

Badge

Button

Calendar

Card

CardContent

CardDescription

CardFooter

CardHeader

CardTitle

Chart

Checkbox

Dialog

DropdownMenu

Input

Label

Pagination

Popover

Progress

RadioGroup

Select

Separator

Sheet

Sidebar

Skeleton

Sonner

Switch

Table

Tabs

Textarea

Toast

Toaster

Toggle

Tooltip

注意： 如果你需要构建自己的 UI，请直接安装 shadcn/ui（
npx shadcn@latest add ...
），不要从 SDK 中导入这些组件。SDK 导出的这些组件仅用于内部使用和 SDK 组件自定义。

Component Priority

组件使用优先级

ibl.ai components first -- always use the native component when one exists
shadcn/ui for everything else -- forms, tables, modals, date pickers, etc.:
bash
```
npx shadcn@latest add button dialog table form
```
shadcnspace blocks -- pre-built page sections:
bash
```
npx shadcn@latest add @shadcn-space/hero-01
```

ibl.ai and shadcn components share the same Tailwind theme and are visually seamless.

优先使用 ibl.ai 组件——如果有原生组件存在时请始终使用原生组件
其他需求使用 shadcn/ui——表单、表格、弹窗、日期选择器等：
bash
```
npx shadcn@latest add button dialog table form
```
shadcnspace 区块——预构建的页面区块：
bash
```
npx shadcn@latest add @shadcn-space/hero-01
```

ibl.ai 和 shadcn 组件共享同一套 Tailwind 主题，视觉上完全统一。

CLI Updates

CLI 更新

Before running any

iblai

command, ensure the CLI is up to date. Run

iblai --version

to check the current version, then upgrade directly:

pip:
```
pip install --upgrade iblai-app-cli
```
npm:
```
npm install -g @iblai/cli@latest
```

This is safe to run even if already at the latest version.

在运行任何

iblai

命令前，请确保 CLI 是最新版本。运行

iblai --version

查看当前版本，然后直接升级：

pip:
```
pip install --upgrade iblai-app-cli
```
npm:
```
npm install -g @iblai/cli@latest
```

即使已经是最新版本，运行该命令也是安全的。

Requirements

要求

Next.js App Router project (app/ directory)
Node.js 18+
```
iblai
```
CLI available (
```
iblai --version
```
). See
```
/iblai-auth
```
prerequisites for installation.
Run
```
iblai add mcp
```
first to set up MCP servers and skills
If you started with
```
npx create-next-app@latest
```
, run
```
iblai add auth
```
first -- other components depend on the auth providers
If you used
```
iblai startapp agent
```
, auth is already set up
Brand guidelines: BRAND.md

Next.js App Router 项目（app/ 目录结构）
Node.js 18+
可用的
```
iblai
```
CLI（执行
```
iblai --version
```
验证）。查看
```
/iblai-auth
```
前置条件了解安装方式
请先运行
```
iblai add mcp
```
设置 MCP 服务器和 skills
如果你是从
```
npx create-next-app@latest
```
初始化的项目，请先运行
```
iblai add auth
```
——其他组件依赖鉴权提供者
如果你使用
```
iblai startapp agent
```
创建项目，鉴权已经预配置完成
品牌规范: BRAND.md