# 更新日志 (/docs/changelog) ## 2026-06-10 [#2026-06-10] * 解除速率限制，全面放开，不再限制查询参数访问 ## 2026-06-04 [#2026-06-04] * 凭据仅支持通过链接配置，不再提供手动输入 * 已配置的凭据只能删除，无法修改 * 移除文档页内的 GitHub 入口 ## 2026-06-03 [#2026-06-03] ### MCP 工具更新 [#mcp-工具更新] * 上游 MCP 从 Pro-only 4 工具升级为 Pro + OSS 统一 9 工具，详见 [Local MCP — 工具更新](/docs/ai-tools/mcp#2026-06-03-工具更新) ## 2026-06-02 [#2026-06-02] ### 修复 MCP 文档链接 [#修复-mcp-文档链接] * 修复首页和 Skills 页中指向 `/docs/ai-tools/mcp/local` 的错误链接，改为正确路径 `/docs/ai-tools/mcp` ## 2026-06-01 [#2026-06-01] ### 安装命令支持多包管理器 [#安装命令支持多包管理器] * `hpsetup` 安装命令现在以 Tabs 形式展示 npm / pnpm / bun / yarn 四种包管理器的等效命令 ## 2026-05-31 [#2026-05-31] ### 用户反馈系统上线 [#用户反馈系统上线] * 新增页级反馈：文档底部 Good/Bad 评分，支持文字反馈 * 新增块级反馈：选中文字后弹出反馈框，精确定位到具体段落 * 反馈内容通过 Resend 实时发送至邮箱 ### 文档更新时间显示 [#文档更新时间显示] * 所有文档页面底部显示最后更新日期（基于 frontmatter `date` 字段） ### LLM 文档入口 [#llm-文档入口] * 侧边栏图标栏新增 llms.txt 和 llms-full.txt 快捷入口，方便 AI 工具直接抓取文档 * hover 显示 tooltip 说明（索引 / 完整文档） ### 凭据状态指示器 [#凭据状态指示器] * 侧边栏图标栏新增凭据状态圆点，实时反映 personal token 配置状态 * 已配置时显示绿色呼吸灯动画，hover 显示凭据详情和清除按钮 * 未配置时显示灰色圆点，点击跳转到凭据配置区域 ### 凭据配置组件优化 [#凭据配置组件优化] * 保存按钮移至头部右侧，回车快捷保存 * 已配置卡片显示 HP Key / Personal Token 独立状态 badge * 支持一键删除凭据 ## 2026-05-30 [#2026-05-30] ### TOC 样式升级 [#toc-样式升级] * 目录（On this page）切换为 Clerk 风格，带树状连接线和高亮指示器 ### Monorepo 文档上线 [#monorepo-文档上线] * 新增 Default Monorepo 文档：单 Web 端 monorepo 安装指南（基于 Better T Stack） * 原 Monorepo 文档拆分为 Default / Web + Native 两篇，侧边栏新增 Monorepo 分组 ## 2026-05-22 [#2026-05-22] ### 站点清理 [#站点清理] * 移除 Ask AI 浮窗功能 ### hpsetup 用法页上线 [#hpsetup-用法页上线] * 新增完整的 hpsetup 用法文档，覆盖 CI、Vercel、Monorepo 等场景 * 安装命令统一为 npx，组件支持动态 key 注入 * hpsetup 文档链接更新至新路径 ### hpsetup 文档优化 [#hpsetup-文档优化] * 新增「工作原理」页，详解安装流程与模块职责 * 命令行参数独立成页，方便查阅 ### 私有仓库重构 [#私有仓库重构] * 组件源码仓库从 hp-components 重命名为 hp-component-docs * 组件文档改用 md 格式替代纯 tsx 代码 ### 重构 Web 快速开始文档 [#重构-web-快速开始文档] * 新增「一步到位」模板克隆方式，克隆即可用 * 手动安装拆分为项目准备、安装 HeroUI Pro、引入 demo 组件三个子章节 * 包管理器 tabs 全局联动，切换一次即可同步所有命令 * 新增常见问题：HeroUI CLI 选项说明、ERR\_PNPM\_IGNORED\_BUILDS 报错处理 ## 2026-05-21 [#2026-05-21] ### 首页重写 & 凭据卡片升级 [#首页重写--凭据卡片升级] * 首页改为 FAQ 式简介 + 分步引导，更易懂 * 凭据配置卡片视觉升级：绿色主题、ping 动画、圆角样式 ### Skills 安装命令代码块修复 [#skills-安装命令代码块修复] * 修复 Skills 安装命令丢失语法高亮和一键复制按钮的问题 ## 2026-05-20 [#2026-05-20] ### Monorepo 文档补充初始化步骤 [#monorepo-文档补充初始化步骤] * 新增"创建项目"步骤，使用 `pnpm create better-t-stack@latest` 初始化包含 Turborepo 的 monorepo 项目 * 新增"运行 hpsetup"小节，与原有"配置样式"部分衔接 * 添加站点公告 Banner，提示文档更新及近期迭代计划 ### 侧边栏更新提示 [#侧边栏更新提示] * 侧边栏新增 "New" 标记，提示有更新的文档页面 * 点击该页面后标记自动消失 * 点击后直接跳转到对应更新内容的子标题 ## 2026-05-16 [#2026-05-16] ### 快速开始文档重构 [#快速开始文档重构] * 新增"验证运行"步骤，安装依赖后先确认项目能正常启动 * 新增"初始化 Git"步骤（可选），安装 Pro 前提交基线版本 * "引入样式"和"使用组件"步骤按框架分栏展示（Next.js / Vite / Pages） * 新增更多截图，直观展示安装和运行效果 ### 凭据链接即时生效 [#凭据链接即时生效] * 修复通过 URL 参数传入凭据后，配置卡片不会立即显示"已就绪"状态的问题 ### 文档体验优化 [#文档体验优化] * 命令示例按包管理器分栏展示（pnpm / Bun / npm），方便选择 * 增加提示信息卡片，提升可读性 * 不推荐使用 Yarn 的说明以醒目提示形式展示 # 简介 (/docs) 请认准 [CollectUI](https://e.tb.cn/h.RiZXMqfQxiJVXH3?tk=4i5Ng093BkD)（店铺同名）。非 CollectUI 店铺提供的 key/token 近期内将会被暂停或封禁。 抱歉，诸位。 由于个别买家照搬销售的缘故，紧急开启了**速率限制**，且颇为严格。 这里边，难免有误伤。尤其是**带参数访问、多 IP 使用、CI 部署**的时候。 抱歉，给大家添麻烦了。 以后非必要不会这么干的。就算这么干，也会**放宽一些**，尽可能不影响大家的正常使用。 另外，相关卖家已经下架了。所以之前加的限制也已**同步解除，全面放开**。 大家可以和亲友共享，也可以在团队内部使用，不设额外限制（本来也没打算限制）。 不过，仍然禁止在淘鱼照搬销售和大范围共享（**10 人以上**），系统保留了观察和限制的能力，可以应对，并快速采取措施。 ## 这是什么？ [#这是什么] [heroui v3 pro](https://heroui.pro) 😎（或者叫 heroui pro v3 也成）。 当然，不是账密，也不共享官 key（官方有风控）。 不过有办法使用，体验和结果和官方基本一致。 ## 和官方的有什么区别？ [#和官方的有什么区别] 区别是： * 没有账密 * 不能使用网页访问（镜像上线后可用） * 不能使用 [pro theme builder](https://heroui.pro/dashboard/themes)（镜像上线后可用） * 使用 [hpsetup cli](/docs/hpsetup/usage)（官方复刻）安装 pro 依赖而非 [heroui-pro cli](https://www.npmjs.com/package/heroui-pro)（官方） * mcp、skills 走转发而非直连 ## 是官网最新的吗？ [#是官网最新的吗] 当然😎。 * [hpsetup](/docs/hpsetup/usage) 一运行，就会从 npm 获取官方包的最新版本，然后更新、应用到项目 * [hpmcp](/docs/ai-tools/mcp) 发出的请求，间隔一段时间就会直达上游，忽略缓存 ## 完整吗？ [#完整吗] 当然😎，服务端有授权，随时可以从官方获取。 ## MCP 和 Skills 都能用吧？ [#mcp-和-skills-都能用吧] 当然😎，看图： PixPin_2026-05-21_01-43-59 image-20260521014449141 PixPin_2026-05-21_02-38-33 ## 永久可用吗？ [#永久可用吗] 当然😎，所有的工具请求的资源都有全量备份（不断更新）。万一上游不可用，会自动 fallback，不至于服务中断。 ## 永久更新吗？ [#永久更新吗] 不，官方的套餐里边没有永久的选项，需要一年一续。 所以只能更新到套餐结束 —— 2027年5月1日。 ## 遇到 Bug 咋办？ [#遇到-bug-咋办] 随时滴滴，我都在的😎。 大部分时间都在，没在那可能是睡着了，通知铃声没吵醒我😂。 ## 接下来做什么？ [#接下来做什么] ### 配置凭据 [#配置凭据] hpsetup 需要一个 hp key，mcp 和 skills 需要一个 personal token。两者不同，可以在下边统一配置，之后所有页面都会内嵌真实的 key/token，方便复制。 非 [CollectUI](https://e.tb.cn/h.RiZXMqfQxiJVXH3?tk=4i5Ng093BkD) 店铺购买的 key/token 无法通过链接设置，此类 key/token 可能随时暂停或吊销。 ### 安装 Pro 依赖 [#安装-pro-依赖] 从 [hpsetup](/docs/hpsetup/usage) 开始，安装 pro 依赖（pro 组件和模板都需要这个）。 ### 配置 AI 工具 [#配置-ai-工具] 配置 [mcp](/docs/ai-tools/mcp) 和 [skills](/docs/ai-tools/skills)，用 AI 辅助开发。 # 速率限制 (/docs/rate-limit) 此限制主要针对在闲鱼等平台复制销售的卖家，正常用户使用不受影响（足够个人使用）。 原来没想对共享使用做任何限制，但最近在平台上发现完全照搬的商品，故不得不作此限制。 此限制在平台无照搬竞品时，适时撤销。 ## 安装限制（hpsetup） [#安装限制hpsetup] | 使用方式 | 每天配额 | | ------------ | --------------- | | 交互模式（本地开发） | **5 次**（同一设备无限） | | CI 模式（自动化构建） | **20 次** | 同一版本的 Pro 依赖是固定的，官方 CLI 安装后会自动缓存到本地。下次安装同版本时直接用缓存，**不消耗配额**——所以在同一台设备上，装过一次就等于无限次。 配额每天零点（UTC）自动重置。超出配额后返回 429 错误。 `--no-cache` 强制绕过缓存从源站拉取，全局每天 **1 次**（所有用户共享），超出后返回 `Source fetch limit reached for today.` *** ## MCP 请求限制 [#mcp-请求限制] 每个 Token 每秒最多 **20 次**请求——正常写代码完全够用，相当于你每秒狂按 10 次键盘。 但如果像机器人一样不停请求（比如用脚本爬取），系统会自动踩刹车： | 行为 | 后果 | | ------------ | ------------ | | 短时间疯狂请求被拦多次 | 暂停 **3 小时** | | 长时间持续高频被拦多次 | 暂停 **6 小时** | | 连续批量爬取不停 | 暂停 **12 小时** | | 多人共用同一 Token | 暂停 **24 小时** | 暂停到期后违规记录不会清零，继续犯会更快被停。累计 **3 次**暂停 = 永久吊销。 *** ## 汇总 [#汇总] | 类型 | 配额 | 说明 | | ------------ | ------------ | ------------------ | | 交互模式安装 | 每天 **5 次** | 同一设备无限（用缓存） | | CI 模式安装 | 每天 **20 次** | 无本地缓存，每次都计 | | `--no-cache` | 全局每天 **1 次** | 所有用户共享 | | MCP 请求 | 每秒 **20 次** | 正常开发绰绰有余，多人共用会触发暂停 | | `--dry-run` | **无限制** | 不消耗任何配额 | 如有疑问，请联系 [CollectUI](https://e.tb.cn/h.RiZXMqfQxiJVXH3?tk=4i5Ng093BkD) 店铺客服（非 CollectUI 店铺购买不提供支持）。 # Local MCP (/docs/ai-tools/mcp) > 本文由 GLM-5.1 驱动的 CC 基于项目源码生成。 `hpmcp` 是 HeroUI Pro MCP Server 的本地代理。自动缓存上游响应，离线时仍可使用。 *** ## 2026-06-03 工具更新 [#2026-06-03-工具更新] 上游 MCP 已从 **Pro-only（4 个工具）** 升级为 **Pro + OSS 统一（9 个工具）**。`hpmcp` 会自动同步，无需更新配置。 ### 新增工具（5 个） [#新增工具5-个] | 工具 | 说明 | | --------------------------- | -------------------------------------------------------- | | `get_component_source_code` | 获取 OSS 组件的 React/TypeScript 源码（仅 `@heroui/react`，不含 Pro） | | `get_chat_export_manifest` | 获取 HeroUI AI Chat 导出的文件清单（commitSha、文件列表、预览 URL） | | `get_chat_export_files` | 根据 manifest 拉取指定的导出文件内容 | | `get_theme_variables` | 获取主题变量和 design tokens（default、brutalism、glass、mouve） | ### 已有工具变化 [#已有工具变化] | 工具 | 旧版 | 新版 | | -------------------- | ---------------- | ------------------------------------------- | | `list_components` | 仅列 Pro 组件 | Pro + OSS 统一列表（133 个） | | `get_component_docs` | 固定 enum，仅 Pro | 自由 string 数组，Pro + OSS | | `get_css` | 仅 Pro，含 theme 参数 | Pro + OSS，theme 参数独立到 `get_theme_variables` | | `get_docs` | 20 个 Pro 文档路径 | 大幅扩充，新增 `/pro/docs/react/...` 及更多 OSS 路径 | MCP 不再区分 Pro 和 OSS 两套服务 — 一份配置即可访问所有组件的文档、源码和主题变量。如果之前单独配置过 OSS MCP，可以移除。 # Agent Skills (/docs/ai-tools/skills) > 本文由 GLM-5.1 驱动的 CC 参考官方文档生成。 HeroUI Pro 提供 **Skills（技能包）**，是教 AI 代理正确使用 Pro 组件的知识库。包含组件模式、API 约定和设计原则。 Skills 是缓存的知识，离线可用，代理启动时自动加载。与 [MCP](/docs/ai-tools/mcp) 实时数据配合使用效果最佳。 *** ## 安装 [#安装] `@heroui-pro/react` — 图表、高级表单、导航、浮层、数据展示，共 55 个组件。 `heroui-native-pro` — 日期选择器、步进器、进度按钮、滑动按钮、数字输入框，共 30 个组件。 `heroui-pro-design-taste` — 78 条设计原则，覆盖 10 个分类，适用于所有 HeroUI 包。 Skills 使用的是 **Personal Token**，不是 hpsetup 的 HP Key，两者是不同的认证体系，请勿混用。 *** ## 支持的 AI 工具 [#支持的-ai-工具] 安装脚本会自动检测已安装的工具并安装到对应目录： | AI 工具 | 安装路径 | | -------------------- | -------------------------------------------- | | Claude Code | `~/.claude/skills/{skill-name}/` | | Cursor | `~/.cursor/skills/{skill-name}/` | | Codex CLI | `~/.codex/skills/{skill-name}/` | | OpenCode | `~/.config/opencode/skill/{skill-name}/` | | Antigravity (Gemini) | `~/.gemini/antigravity/skills/{skill-name}/` | 如果没有检测到已安装的 AI 工具，脚本会输出下载链接。也可以设置 `HEROUI_PRO_SKILLS_DIR` 安装到自定义路径。 *** ## 技能包详情 [#技能包详情] ### heroui-react-pro [#heroui-react-pro] `@heroui-pro/react` 的复合组件模式、MCP 工具用法和 CSS 样式系统。 **覆盖范围：** * 图表：AreaChart、BarChart、LineChart、PieChart、RadarChart、ComposedChart * 数据展示：KPI、KPIGroup、TrendChip、NumberValue、Rating、EmptyState * 表单：CellSelect、CellSwitch、CellSlider、InlineSelect、NativeSelect、NumberStepper * 导航：Sidebar、FloatingToc、Stepper、Segment * 浮层：Command、ContextMenu、HoverCard、Sheet * 反馈：PressableFeedback、DropZone、EmojiPicker * 布局：FileTree、Kanban、ItemCard ### heroui-native-pro [#heroui-native-pro] `heroui-native-pro` 的复合组件模式、Uniwind 样式和 Reanimated 约定。 **覆盖范围：** * 日期时间：DatePicker、DateRangePicker、RangeCalendar、Calendar * 表单：NumberField、NumberStepper、RadioButtonGroup * 按钮：ProgressButton、SlideButton、ToggleButton、SocialAuthButton、ToggleButtonGroup * 导航：Stepper、Segment、SplitView * 数据展示：NumberValue、Rating、ProgressBar、ProgressCircle、EmptyState、Badge * 图表：AreaChart、BarChart、LineChart ### heroui-pro-design-taste [#heroui-pro-design-taste] 78 条设计原则，覆盖 10 个分类，适用于所有 HeroUI 包。 **分类：** 间距、排版、颜色、卡片、表单、按钮、图标、导航、布局、无障碍。 *** ## 卸载 [#卸载] 删除对应目录即可： ```bash rm -rf ~/.claude/skills/heroui-react-pro rm -rf ~/.claude/skills/heroui-native-pro rm -rf ~/.claude/skills/heroui-pro-design-taste ``` # 工作原理 (/docs/hpsetup/architecture) > 本文由 GLM-5-turbo 驱动的 CC 根据项目源码生成 ## 一句话总结 [#一句话总结] hpsetup 通过 API Key 认证从 CDN 下载 HeroUI Pro 的闭源组件 tarball，解压到本地 `node_modules` 中已有的 stub 包内，再自动补齐 peer 依赖和包管理器信任配置。 ## 安装全流程 [#安装全流程] ``` npx -y hpsetup@latest hp_xxxx │ ▼ ┌─────────────┐ │ 1. 环境检测 │ 包管理器 · monorepo · 平台类型 └──────┬──────┘ ▼ ┌─────────────┐ │ 2. 产品发现 │ 扫描 node_modules · 识别已装版本 └──────┬──────┘ ▼ ┌─────────────┐ │ 3. 版本校验 │ npm registry 查最新 · 过期则升级 └──────┬──────┘ ▼ ┌─────────────┐ │ 4. 下载产物 │ CDN → 本地缓存 fallback └──────┬──────┘ ▼ ┌─────────────┐ │ 5. 信任配置 │ pnpm allowBuilds · bun trustedDeps └──────┬──────┘ ▼ ┌─────────────┐ │ 6. Peer 依赖 │ 扫描缺失 · 交互确认 · 分 workspace 安装 └──────┬──────┘ ▼ ┌─────────────┐ │ 7. 收尾 │ patch package.json · Vercel 配置 └─────────────┘ ``` ## 模块职责 [#模块职责] 解析 CLI 参数和环境变量，决定交互模式还是自动模式。 唯一的流程控制中心，串联以下所有模块。 扫描 node\_modules、识别 workspace 结构、检测平台类型（Web / Native）。 统一 npm / yarn / pnpm / bun 的 install 命令和 flag 差异。 查询 npm registry 最新版本，带递增超时重试（3s → 6s → 10s）。 从 CDN 拉取 tarball 并解压。失败时回退到本地缓存。 缓存目录 `~/.heroui/cache///`，同版本跳过下载。 扫描缺失的 peer 依赖，处理 Expo SDK 版本兼容映射。 pnpm `allowBuilds` / `onlyBuiltDependencies`，bun `trustedDependencies`。 修改 node\_modules 中 Pro 包的 package.json 导出路径。 自动在 vercel.json 中写入 installCommand。 产品定义、peer 依赖列表、Expo SDK 兼容表、CDN 地址。 ## 关键机制详解 [#关键机制详解] ### Stub 包与真实产物 [#stub-包与真实产物] npm 上的 HeroUI Pro 包是 **stub 包**——只包含一个 `postinstall` 脚本，不含真实组件代码。hpsetup 的工作就是： . 用 `--ignore-scripts` 安装 stub 包（使 `node_modules/@heroui-pro/react` 目录存在） . 从 CDN 下载包含真实组件代码的 tarball . 解压到 stub 包目录中，覆盖空壳内容 hpsetup 通过检查产物目录中是否存在 `index.js` 或 `index.mjs` 来判断"是否已安装真实代码"，而非仅看包是否存在。 ### Monorepo 支持 [#monorepo-支持] hpsetup 自动检测 workspace 结构（`package.json` 的 `workspaces` 字段、`pnpm-workspace.yaml`），并智能定位安装目标： * **自动识别平台**：通过依赖和配置文件判断每个 workspace 是 Web 还是 Native 项目 * **精确安装**：React Pro 只装到 Web workspace，Native Pro 只装到 Native workspace * **跳过共享库**：`packages/*` 路径下的纯库包不会被作为安装目标 * **分 workspace 安装 peer 依赖**：每个 workspace 独立扫描、独立安装 ### 下载容错 [#下载容错] ``` CDN 下载 → 当前版本缓存 → 上一版本缓存 → 退出报错 ``` 三层 fallback 确保在网络波动或 CDN 不可用时仍能完成安装。 ### 包管理器信任 [#包管理器信任] HeroUI Pro 包含 postinstall 脚本，需要包管理器信任才能执行。hpsetup 自动处理： | 包管理器 | 信任方式 | | ----------------- | ------------------------------------------------ | | pnpm（有 workspace） | `pnpm-workspace.yaml` 的 `allowBuilds` 字段 | | pnpm（无 workspace） | `package.json` 的 `pnpm.onlyBuiltDependencies` 字段 | | bun | `package.json` 的 `trustedDependencies` 字段 | | npm / yarn | 无需额外配置 | ### Vercel 集成 [#vercel-集成] 当检测到 Next.js 项目时（存在 `next.config.*` 或 `vercel.json`），hpsetup 会提示在 `vercel.json` 中写入 `installCommand`，使 Vercel 构建时自动运行 hpsetup。同时将 `vercel.json` 加入 `.gitignore`，避免泄露 API Key。 ### Expo SDK 兼容 [#expo-sdk-兼容] 安装 Native Pro 时，hpsetup 读取项目中的 Expo SDK 主版本号，自动将 peer 依赖版本映射到 Expo 兼容的固定版本： | Expo SDK | `@shopify/react-native-skia` | | -------- | ---------------------------- | | 52 | 1.5.0 | | 53 | 2.0.0-next.4 | | 54 | 2.2.12 | | 55 | 2.4.18 | 这些版本通过 `npx expo install` 逐个 SDK 测试确认兼容。 ## 交互模式 vs 自动模式 [#交互模式-vs-自动模式] | | 交互模式 | 自动模式（`--auto` 或 CI） | | ------------ | ----------- | -------------------- | | 触发条件 | TTY 终端 | `CI=true` 或 `--auto` | | 产品选择 | 多选菜单 | 从 package.json 自动推断 | | Workspace 选择 | 多选菜单 | 全部匹配的 workspace | | Peer 依赖确认 | 多选菜单（可取消勾选） | 全部安装，无确认 | | Vercel 配置 | 询问确认 | 直接写入 | ## 已知限制 [#已知限制] * **不支持 Yarn Berry PnP**：需在 `.yarnrc.yml` 中添加 `nodeLinker: node-modules`，或使用其他包管理器 * **pnpm + Vite**：可能出现 `does not provide an export named 'jsx'` 错误，需在 `vite.config` 中添加 `optimizeDeps.include` * **`--no-cache` 频率限制**：每日最多 1 次，超限返回 429 # 用法 (/docs/hpsetup/usage) > 本文由 GLM-5-turbo 驱动的 CC 根据项目源码生成 ## 前置条件 [#前置条件] * **Node.js 18+** * 任一包管理器：npm / pnpm / yarn / bun * Yarn Berry PnP **不支持**，需切换为 `node-modules` linker * 有效的 API Key（以 `hp_` 开头） ## 基本用法 [#基本用法] 首次运行进入交互模式，hpsetup 会引导你完成所有步骤——你只需要按提示操作。 ### 一个完整示例 [#一个完整示例] 假设你的项目是一个使用 pnpm 的 Next.js 项目： ```bash # 1. 运行 hpsetup npx -y hpsetup@latest # 2. 选择产品（多选菜单） # ◉ HeroUI React Pro # ○ HeroUI Native Pro # 3. 检测已装包 → 查询最新版本 → 下载组件代码 # 4. 选择要安装的 peer 依赖（已全选，回车确认） # ◉ @heroui/react # ◉ @heroui/styles # ◉ tailwindcss # ... # 5. 完成 # ✓ HeroUI React Pro v1.2.3 installed successfully. ``` 之后每次运行，如果已是最新版本，hpsetup 会提示： ``` ✓ HeroUI React Pro v1.2.3 — already on the latest version. Nothing to do. ``` ## 指定产品 [#指定产品] 只安装 Native Pro： | 参数 | 产品 | 包名 | | -------- | ----------------- | ------------------- | | `react` | HeroUI React Pro | `@heroui-pro/react` | | `native` | HeroUI Native Pro | `heroui-native-pro` | 不指定时进入交互式选择。 ## 自动模式（CI / 脚本） [#自动模式ci--脚本] 在 CI 环境或脚本中运行时，不需要任何交互： 设置 `HEROUI_KEY` 环境变量后，hpsetup 自动跳过所有交互提示，从 `package.json` 推断要安装的产品。 ### 也可用 `--auto` 手动触发 [#也可用---auto-手动触发] CI 环境自带 `CI=true` 变量，hpsetup 会自动检测，无需额外传参。 ## 常用选项 [#常用选项] | 选项 | 作用 | | ------------ | --------------------- | | `--auto` | 跳过交互提示，自动检测并安装 | | `--dry-run` | 只显示将执行的操作，不做任何更改 | | `--no-cache` | 绕过缓存，强制从源站拉取（每日限 1 次） | | `-h, --help` | 显示帮助信息 | ### 预览变更（dry-run） [#预览变更dry-run] 不确定 hpsetup 会做什么？先 dry-run： 输出类似： ``` [dry-run] Would install: @heroui-pro/react [dry-run] Would download HeroUI React Pro v1.2.3 from CDN [dry-run] Would install peers: @heroui/react@"^2.7.0", tailwindcss@"latest" ``` ### 强制刷新缓存 [#强制刷新缓存] 绕过本地缓存和 CDN 缓存，直接从源站拉取最新包。 `--no-cache` 每天最多使用 1 次，超出会返回 429 错误。 ## GitHub Actions [#github-actions] 将 API Key 存入仓库 Secrets，在 workflow 中使用： ```yaml name: CI on: [push, pull_request] jobs: build: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: actions/setup-node@v4 with: node-version: 20 - run: npx -y hpsetup@latest env: HEROUI_KEY: ${{ secrets.HEROUI_KEY }} ``` ## Vercel [#vercel] ### 首次运行时自动配置 [#首次运行时自动配置] hpsetup 检测到 Next.js 项目后，会询问是否写入 `vercel.json`： ``` Write vercel.json with installCommand for Vercel CI? [Y/n] ``` 确认后会： . 在 `vercel.json` 中写入 `installCommand` . 将 `vercel.json` 加入 `.gitignore`（防止泄露 API Key） ### 手动配置 [#手动配置] 在 Vercel 控制台中： . **Settings → Build & Development Settings → Install Command** 填入： ``` npx -y hpsetup@latest ``` . **Environment Variables** 添加： * Name: `HEROUI_KEY` * Value: 你的 API Key Vercel Build 环境自带 `CI=true`，hpsetup 会自动进入非交互模式。 ## Monorepo [#monorepo] hpsetup 自动识别 monorepo 结构（`workspaces` 字段或 `pnpm-workspace.yaml`），无需额外配置。 ### 自动行为 [#自动行为] * 扫描所有 workspace，识别每个 workspace 的平台类型（Web / Native） * React Pro 只安装到 Web workspace，Native Pro 只安装到 Native workspace * 跳过 `packages/*` 下的共享库 * Peer 依赖按 workspace 独立扫描、独立安装 ### 交互模式下选择 workspace [#交互模式下选择-workspace] 当有多个匹配的 workspace 时，会出现多选菜单让你选择安装目标。 ### 自动模式下 [#自动模式下] 所有匹配的 workspace 都会被安装，无需手动指定。 ## 包管理器 [#包管理器] hpsetup 自动检测当前项目使用的包管理器： | 检测方式 | 优先级 | | ---------------------------------------- | ----- | | lockfile（`pnpm-lock.yaml`、`yarn.lock` 等） | 最高 | | `package.json` 的 `packageManager` 字段 | 中 | | `npm_config_user_agent` 环境变量 | 低 | | 默认 | `npm` | ### 各包管理器的特殊处理 [#各包管理器的特殊处理] **pnpm：** * 自动将 Pro 包加入 `pnpm-workspace.yaml` 的 `allowBuilds` * 如果有 pending build approvals，会提示运行 `pnpm approve-builds` **bun：** * 自动将 Pro 包加入 `package.json` 的 `trustedDependencies` **npm：** * 安装时自动附加 `--legacy-peer-deps` **yarn：** * 仅支持 Yarn Classic，不支持 PnP ## 本地缓存 [#本地缓存] 下载的组件代码缓存在 `~/.heroui/cache/` 目录下，按产品和版本组织： ``` ~/.heroui/cache/ ├── react/ │ ├── 1.0.0-beta.3/ │ └── 1.0.0-beta.4/ └── react-native/ └── 1.0.0-beta.4/ ``` 相同版本不会重复下载，直接从缓存恢复。 ## 日常使用流程 [#日常使用流程] ### 安装 [#安装] ### 更新 [#更新] 再次运行同样的命令即可。hpsetup 会自动检测新版本并更新。 ### CI / 构建 [#ci--构建] 在 CI 配置中使用 `HEROUI_KEY` 环境变量，每次构建自动拉取最新版本。 ### 排查问题 [#排查问题] 使用 `--dry-run` 查看将执行的操作，或 `--no-cache` 强制重新下载。 ## 常见问题 [#常见问题] ### pnpm + Vite 的 JSX 报错 [#pnpm--vite-的-jsx-报错] `does not provide an export named 'jsx'` 这是 pnpm 严格依赖隔离的副作用。pnpm 通过符号链接组织 `node_modules`，Pro 组件的 JSX 转换依赖的 `react/jsx-runtime` 可能被解析到 Pro 包自带的副本，而非项目根目录的 React。Vite 的预构建（pre-bundling）不会自动处理这种路径差异，导致 JSX 导出找不到。 在 `vite.config.ts` 中手动声明依赖预构建，让 Vite 将它们打包到同一个模块中即可解决： ```ts export default defineConfig({ optimizeDeps: { include: ["react", "react/jsx-runtime", "@heroui-pro/react"], }, }) ``` # Default Monorepo (/docs/monorepo/default-monorepo) > 本文由人工撰写（md），AI 优化（mdx）。 用 [Better T Stack](https://www.better-t-stack.dev/) 创建一个默认 monorepo（[直达 Builder](https://better-t-stack.dev/stack?name=my-better-t-app\&fe-w=tanstack-router\&fe-n=none\&rt=bun\&be=hono\&api=trpc\&db=sqlite\&orm=drizzle\&dbs=none\&au=better-auth\&pay=none\&pm=bun\&add=turborepo\&ex=none\&git=true\&i=true\&wd=none\&sd=none\&yolo=false)）。 技术栈： 技术栈选择 上边的 `Bun` 是运行时，下边的 `bun` 是包管理器。（bun 即能做运行时，又能做包管理器） 另外，选择其他的栈也是可以的，只是安装选择和具体路径可能不同，下边以此栈为例。 ## 一步到位 [#一步到位] 跳过手动安装的过程，直接使用基于当前示例的模板。 克隆[模板](https://github.com/rhywonfeong/hp-default-monorepo-template) ```bash npx -y degit rhywonfeong/hp-default-monorepo-template my-better-t-app cd my-better-t-app ``` `degit` 会克隆仓库，但丢弃远程的 git 历史。 确保已安装 [p cli](https://github.com/ru-yaka/p)，然后在任意路径下执行： ```bash p clone --degit rhywonfeong/hp-default-monorepo-template my-better-t-app ``` 它会以 degit 模式克隆远程仓库，放到统一的项目目录下（方便管理），并用 IDE 打开（默认 cursor）。 安装依赖 ```bash bun install ``` 运行 hpsetup 启动预览 ```bash bun dev ``` ## 手动安装 [#手动安装] CLI 创建 ```bash bun create better-t-stack@latest my-better-t-app --yes ``` 默认配置的命令是最简洁的，稍作修改，就会出现很多 flag 选项。 验证运行（可选） dev 预览一下，看是否正常。 ```bash bun dev ``` 验证运行 没问题，关掉，然后继续。 暂存提交（可选） 建议提交一次，方便之后查看变更，如果改坏了也可以快速撤回。 git status 有一个初始提交（better-t-stack 自动执行），两个变更（一个自动生成的，一个暂时为空的本地 db）。 全部忽略： ```bash title=".gitignore" # Custom Ignore local.db *.gen.ts ``` 暂存提交： ```bash git add -A && git commit -m "wip: checkpoint before next changes" ``` ```bash git add -A; git commit -m "wip: checkpoint before next changes" ``` ### 安装 HeroUI Pro [#安装-heroui-pro] 运行 hpsetup 在 **根目录** 下运行 hpsetup： hpsetup 支持 monorepo，可以直接在根目录运行，add、安装到子项目，不用 cd 进去，官方 CLI 不支持。 选择安装 HeroUI React Pro，然后安装所有预选的对等依赖。 也可以部分安装，因为不是每个引入的 pro 组件都需要这些对等依赖。但问题是，你不知道引入的 pro 组件需要什么对等依赖，而且这里边有一些是必须的。 hpsetup 交互式安装 这里的版本是从本地缓存中恢复了，与官方 CLI 行为一致。每个版本的 tarball 是固定的。 也可以自动化进行，适合 CI 场景（会自动识别，不用手动加 `--auto` flag）。 hpsetup 自动化安装 引入 Pro 样式 ```css title="packages/ui/src/styles/globals.css" @import "tailwindcss"; /* [!code ++] */ @import "@heroui/styles"; /* [!code ++] */ @import "@heroui-pro/react/css"; ``` 引入 Pro 样式 引入 Pro 组件 ```tsx title="apps/web/src/components/area-chart-demo.tsx" "use client"; import {Card} from "@heroui/react"; import { ChartTooltip } from "@heroui-pro/react/chart-tooltip"; import {AreaChart} from "@heroui-pro/react/area-chart"; const revenueData = [ {month: "Jan", revenue: 4200}, {month: "Feb", revenue: 5800}, {month: "Mar", revenue: 4900}, {month: "Apr", revenue: 7200}, {month: "May", revenue: 6100}, {month: "Jun", revenue: 8400}, {month: "Jul", revenue: 7800}, {month: "Aug", revenue: 9200}, {month: "Sep", revenue: 8600}, {month: "Oct", revenue: 10200}, {month: "Nov", revenue: 9800}, {month: "Dec", revenue: 11500}, ]; export default function AreaChartDemo() { return ( Monthly Revenue `$${(v / 1000).toFixed(0)}k`} width={40} /> { if (!active || !payload?.length) return null; return ( {label} {payload.map((entry) => ( {entry.name} ${Number(entry.value).toLocaleString()} ))} ); }} /> ); } ``` 注意上边的 import 路径用的是子路径（`@heroui-pro/react/area-chart`），而不是主入口（`@heroui-pro/react`）。如果从主入口导入，可能会触发依赖解析错误或打包异常。详见 [使用子路径导入](/docs/other/heroui-pro-subpath-imports)。 在首页预览 ```tsx title="apps/web/src/routes/index.tsx" import { createFileRoute } from "@tanstack/react-router"; import AreaChartDemo from "@/components/area-chart-demo"; export const Route = createFileRoute("/")({ component: HomeComponent, }); function HomeComponent() { return (
); } ``` 启动开发服务器： ```bash bun dev ``` 组件渲染 ### 移除 shadcn 样式 [#移除-shadcn-样式] 有渲染，无报错，但样式不太对。 老问题，better-t-stack 默认会创建使用 shadcn/ui 的 monorepo。所以我们相当于是在 shadcn/ui 中引入 heroui（v3），两套完全不同的 UI 组件库/框架，导致部分样式异常（heroui 的部分样式被 shadcn 覆盖）。 如此，我们可以彻底移除 shadcn，只用 heroui。 不建议混用，即使当前组件的样式能够修复（移除 shadcn 覆盖 heroui 的那部分样式），以后引入其他组件也可能会出问题。 先移除 `globals.css` 中的其他样式，看是否正常吧。 ```css title="packages/ui/src/styles/globals.css" @import "tailwindcss"; @import "@heroui/styles"; @import "@heroui-pro/react/css"; /* [!code --] */ @import "tw-animate-css"; /* [!code --] */ @import "shadcn/tailwind.css"; /* [!code --] */ @source "../../../apps/**/*.{ts,tsx}"; /* [!code --] */ @source "../**/*.{ts,tsx}"; /* [!code --] */ @custom-variant dark (&:is(.dark *)); /* [!code --] */ :root { ... } /* [!code --] */ .dark { ... } /* [!code --] */ @theme inline { ... } /* [!code --] */ @layer base { ... } ``` 正常渲染 正常渲染😎 当然，shadcn 并没有完全清除，具体清理内容，参见 [shadcn 清理记录](/docs/other/shadcn-cleanup-summary)。 如果想跳过清理过程，也可以直接使用现成的模板。由 [p cli](https://github.com/ru-yaka/p) 基于当前示例发布。 模板预览 快速开始请看 [一步到位](#一步到位)。 # Web + Native Monorepo (/docs/monorepo/web-native-monorepo) > 本文由人工撰写（md），AI 优化（mdx）。 在 Web + Native 全栈 monorepo 中，hpsetup 可以在根目录运行，它会自动检测所有 workspace 中的 Pro 包并进行安装。 ## 创建项目 [#创建项目] 使用 `create better-t-stack` 初始化一个包含 Turborepo 的 monorepo 项目： ```bash pnpm create better-t-stack@latest my-better-t-app \ --frontend tanstack-router native-uniwind \ --backend none \ --runtime none \ --api none \ --auth none \ --payments none \ --database none \ --orm none \ --db-setup none \ --package-manager pnpm \ --git \ --web-deploy none \ --server-deploy none \ --install \ --addons turborepo \ --examples none ``` ## 运行 hpsetup [#运行-hpsetup] 进入项目目录后运行 hpsetup： hpsetup 在 monorepo 中运行 ## 配置样式 [#配置样式] 安装好 Pro 依赖后，需要在各项目的全局 CSS 中引入样式。 ### Web 项目 [#web-项目] ```css title="packages/ui/src/styles/globals.css" @import "tailwindcss"; @import "@heroui/styles"; @import "@heroui-pro/react/css"; ``` ### Native 项目 [#native-项目] ```css title="apps/native/global.css" @import 'tailwindcss'; @import 'uniwind'; @import 'heroui-native/styles'; @import 'heroui-native-pro/styles'; @source './node_modules/heroui-native/lib'; @source './node_modules/heroui-native-pro/lib'; ``` ## 添加示例组件 [#添加示例组件] 在各自项目的 `components/` 目录中创建 Pro 组件。 ### Web：AreaChart [#webareachart] ```tsx title="apps/web/src/components/area-chart-demo.tsx" "use client"; import {Card} from "@heroui/react"; import { ChartTooltip } from "@heroui-pro/react/chart-tooltip"; import {AreaChart} from "@heroui-pro/react/area-chart"; const revenueData = [ {month: "Jan", revenue: 4200}, {month: "Feb", revenue: 5800}, {month: "Mar", revenue: 4900}, {month: "Apr", revenue: 7200}, {month: "May", revenue: 6100}, {month: "Jun", revenue: 8400}, {month: "Jul", revenue: 7800}, {month: "Aug", revenue: 9200}, {month: "Sep", revenue: 8600}, {month: "Oct", revenue: 10200}, {month: "Nov", revenue: 9800}, {month: "Dec", revenue: 11500}, ]; export default function AreaChartDemo() { return ( Monthly Revenue `$${(v / 1000).toFixed(0)}k`} width={40} /> { if (!active || !payload?.length) return null; return ( {label} {payload.map((entry) => ( {entry.name} ${Number(entry.value).toLocaleString()} ))} ); }} /> ); } ``` 注意上边的 import 路径用的是子路径（`@heroui-pro/react/area-chart`），而不是主入口（`@heroui-pro/react`）。如果从主入口导入，可能会触发依赖解析错误或打包异常。详见 [使用子路径导入](/docs/other/heroui-pro-subpath-imports)。 ### Native：Stepper [#nativestepper] ```tsx title="apps/native/components/stepper-demo.tsx" import { Stepper } from 'heroui-native-pro'; import { View } from 'react-native'; export default function StepperDemo() { return ( Account Create your account Profile Set up your profile ); } ``` ## 在页面中引入 [#在页面中引入] ### Web [#web] ```tsx title="apps/web/src/routes/index.tsx" import { createFileRoute } from "@tanstack/react-router"; import AreaChartDemo from "@/components/area-chart-demo"; export const Route = createFileRoute("/")({ component: HomeComponent, }); function HomeComponent() { return (
); } ``` ### Native [#native] ```tsx title="apps/native/app/(drawer)/index.tsx" import { Text, View } from "react-native"; import { Container } from "@/components/container"; import StepperDemo from "@/components/stepper-demo"; export default function Home() { return ( Better T Stack Full-stack TypeScript starter ); } ``` ## 预览 [#预览] 运行 `pnpm run dev` 启动项目。 ## 常见问题 [#常见问题] ### Web：多 React 实例报错 [#web多-react-实例报错] React is null 错误 这是 Vite 预构建导致的多 React 实例问题。`@heroui-pro/react` 内部调用 `React.useMemo` 时 `React` 为 `null`。 **修复**：在 Vite 配置中添加 `dedupe`： ```ts title="vite.config.ts" export default defineConfig({ resolve: { tsconfigPaths: true, dedupe: ["react", "react-dom", "react/jsx-runtime"], }, // ... }); ``` 修复后正常渲染： AreaChart 正常渲染 ### Web：组件样式异常 [#web组件样式异常] 组件样式异常 这与 shadcn 的主题变量冲突有关。移除 `global.css` 中 shadcn 的主题配置后恢复正常： 移除 shadcn 主题后正常 也可以让 AI 移除 shadcn 中与 HeroUI 冲突的样式来实现混用，但这可能会影响 shadcn 组件的渲染。**建议尽量不混用**。 ### Native：Skia 兼容性 [#nativeskia-兼容性] 如果遇到 `@shopify/react-native-skia` 相关的兼容性警告，需要安装与当前 Expo SDK 兼容的版本： ```bash npx -y expo install @shopify/react-native-skia ``` 修复后正常预览： Native Stepper 正常预览 # HeroUI Native (/docs/native/heroui-native-guide) > 本文由人工撰写（md），AI 优化（mdx）。 克隆 [heroui-native-example](https://github.com/heroui-inc/heroui-native-example) 到本地，然后安装依赖并启动。 ### 克隆项目 [#克隆项目] ```bash git clone https://github.com/heroui-inc/heroui-native-example ``` 确保已安装 [p cli](https://github.com/ru-yaka/p)： ```bash bun install -g ru-yaka/p ``` 然后克隆项目，它会自动放到 `~/.p/projects/` 下并用 IDE（默认 cursor，`p config` 可配）打开： ```bash p clone heroui-inc/heroui-native-example ``` p clone ### 安装依赖 [#安装依赖] ```bash npm install ``` ```bash pnpm install ``` ```bash bun install ``` ```bash yarn install ``` ### 允许构建脚本 [#允许构建脚本] 安装完成后运行 start，pnpm 可能会阻止 `unrs-resolver` 的构建脚本： unrs-resolver 报错 运行 `pnpm approve-builds` 交互式允许（空格选中后回车），也可以直接编辑 `pnpm-workspace.yaml` 设为 true。 unrs-resolver 是 Rust 编写的高性能模块解析器，需要 postinstall 脚本编译对应平台的二进制文件。 ### 启动项目 [#启动项目] ```bash npm run start ``` ```bash pnpm run start ``` ```bash bun run start ``` ```bash yarn start ``` 启动项目 发现有两个依赖不兼容当前的 expo 版本（测试时为 55）。 ### 修复依赖 [#修复依赖] 停止 start，自动安装当前 expo 兼容版本： ```bash npx -y expo install react-native react-native-worklets ``` ```bash pnpm dlx expo install react-native react-native-worklets ``` ```bash bunx expo install react-native react-native-worklets ``` ```bash yarn dlx expo install react-native react-native-worklets ``` 修复依赖 ### 验证运行 [#验证运行] 重新 start，然后用 Expo Go 55 扫码测试。 Expo Go 版本必须和当前 expo SDK 版本匹配，否则无法运行。 一切正常： 运行成功 ## 添加为模板 [#添加为模板] 添加当前项目为模板，下次可以从本地快速新建项目（已修复依赖）： ```bash p tp add . heroui-native ``` ```bash p template add . heroui-native ``` ```bash p templates add . heroui-native ``` p tp add ## 从模板新建项目 [#从模板新建项目] ```bash p new my-heroui-native-app -t heroui-native ``` ```bash p n my-heroui-native-app -t heroui-native ``` ```bash p create my-heroui-native-app -t heroui-native ``` p new `p new ` 可以快速创建项目（放在 `~/.p/projects/` 目录下统一管理），并用配置 IDE 打开（默认 cursor，可 `p config` 配置）。忘记模板名可以 `-t` 留空交互式选择，或 `-t ` 模糊搜索。 # HeroUI Native Pro (/docs/native/heroui-native-pro-guide) > 本文由人工撰写（md），AI 优化（mdx）。 本指南基于已完成的 [HeroUI Native 项目初始化](/docs/native/heroui-native-guide)，请先完成基础项目搭建。 ## 安装 [#安装] 以交互模式安装 heroui-native-pro（完整版）： 在开始之前，可以先初始化 git 并提交，方便查看安装后的具体变更。 安装过程会自动处理 react-native 依赖。如果本地已有缓存（`~/.heroui/cache/react-native/{version}`），会从缓存获取；否则从 CDN 下载后缓存。之后再安装时，同一版本会直接走本地缓存，除非手动清除。 heroui-native-pro 安装过程 ## 配置 [#配置] 安装完成后，需要在全局样式中导入 Pro 的样式和组件源。 ### 导入 Pro 样式 [#导入-pro-样式] 在 `global.css` 中添加 heroui-native-pro 的样式导入和组件源扫描： ```css title="global.css" @import 'tailwindcss'; @import 'uniwind'; @import 'heroui-native/styles'; @import 'heroui-native-pro/styles'; @source './node_modules/heroui-native/lib'; @source './node_modules/heroui-native-pro/lib'; ``` `@source` 路径是相对于 `global.css` 文件而言的。如果 `global.css` 不在项目根目录（例如在 `app/` 中），路径应调整为 `../node_modules/heroui-native-pro/lib`。 ## 使用 [#使用] ### 创建 Pro 组件 [#创建-pro-组件] 在 `components` 目录下创建一个组件文件来使用 Pro 组件： ```tsx title="src/components/my-component.tsx" import { Stepper } from 'heroui-native-pro'; import { View } from 'react-native'; export default function MyComponent() { return ( Account Create your account Profile Set up your profile ); } ``` ### 替换首页内容 [#替换首页内容] 在首页（路径因项目组织方式而异，通常为 `src/app/(home)/index.tsx`）中导入并使用该组件： 替换首页 View 部分 ```tsx title="src/app/(home)/index.tsx" import MyComponent from '@/src/components/my-component'; // 在 ScreenScrollView 中替换 View 部分 ``` ### 预览验证 [#预览验证] 启动项目进行预览： ```bash npm run start ``` ```bash pnpm run start ``` ```bash bun run start ``` ```bash yarn start ``` Stepper 组件预览效果 ## 更新模板 [#更新模板] 安装完成后，可以将当前项目更新为模板（会覆盖原有模板），下次直接使用： ```bash p tp update . ``` ```bash p template update . ``` ```bash p templates update . ``` 更新模板 ## 发布到远程 [#发布到远程] 也可以将模板发布到远程，分享给其他人 clone 使用： ```bash p tp publish . ``` ```bash p template publish . ``` ```bash p templates publish . ``` 发布模板到远程 # Native EAS 部署 (/docs/native/native-eas-build) > 本文由人工撰写（md），AI 优化（mdx）。 本指南基于已完成的 [HeroUI Native Pro 安装](/docs/native/heroui-native-pro-guide)，请先完成基础安装和配置。 ## 配置 preinstall 脚本 [#配置-preinstall-脚本] 切换到 `apps/native/`，在 `package.json` 中新增一个 `preinstall` 脚本： ### 添加 preinstall 脚本 [#添加-preinstall-脚本] ```json title="apps/native/package.json" { "scripts": { "preinstall": "npx -y hpsetup@latest " } } ``` 这一步会确保在依赖安装前运行 hpsetup，提前完成所有依赖的完整安装，然后移除 pro 包的 postinstall（让后续的 install 正常通过，不报依赖构建错误）。 如果需要体验最新的内测实现，可以把 `latest` 换成 `beta`。 ### 配置 EAS [#配置-eas] 新增 `eas.json` 文件： ```json title="apps/native/eas.json" { "cli": { "version": ">= 18.13.0", "appVersionSource": "remote" }, "build": { "development": { "developmentClient": true, "distribution": "internal" }, "preview": { "distribution": "internal" }, "production": { "autoIncrement": true } }, "submit": { "production": {} } } ``` 新增 `.nvmrc`，指定 Node 版本为 22（pnpm 11 需要此版本，否则会报错）： ```bash title="apps/native/.nvmrc" 22 ``` ### 执行构建 [#执行构建] ```bash npx -y --package eas-cli eas build -p android -e preview ``` 临时装一个 eas-cli 包，然后执行其中的 eas 命令，使用 preview profile 运行 Android 端的构建。 成功构建： EAS 构建成功 安装 APK 后运行： APK 安装运行 ## Tips [#tips] ### ERR\_PNPM\_IGNORED\_BUILDS [#err_pnpm_ignored_builds] 如果遇到 `ERR_PNPM_IGNORED_BUILDS` 问题，需要把相应的依赖加入 trust 列表（允许依赖的构建脚本执行）： ERR_PNPM_IGNORED_BUILDS 错误 仅示例，此依赖已纳入 hpsetup trust 列表。 ### Expo 官方插件 [#expo-官方插件] 需要辅助 Expo 开发的话，可以安装官方的插件： Expo 官方插件 # 使用子路径导入 (/docs/other/heroui-pro-subpath-imports) ## 问题 [#问题] 从主入口导入组件时： ```ts import { AreaChart, ChartTooltip } from "@heroui-pro/react"; ``` Vite 会报错，提示找不到 `shiki`、`marked`、`react-markdown` 等依赖： ``` Failed to resolve import "shiki" from "node_modules/.vite/deps/@heroui-pro_react.js" ``` ## 原因 [#原因] `@heroui-pro/react` 的主入口（`dist/index.js`）将所有组件 re-export 到一个文件中。当你从主入口导入时，Vite 必须解析整个 bundle，包括你根本没用到的组件的依赖（`shiki` 属于 `code-block`，`marked` 属于 `markdown`，等等）。 ## 解决方案 [#解决方案] 使用子路径导入，只引入你需要的组件： ```ts // ✅ 正确 — 子路径导入 import { AreaChart } from "@heroui-pro/react/area-chart"; import { ChartTooltip } from "@heroui-pro/react/chart-tooltip"; ``` 所有可用的子路径在包的 `exports` 字段中定义，格式为 `@heroui-pro/react/<组件名>`，例如： * `@heroui-pro/react/area-chart` * `@heroui-pro/react/bar-chart` * `@heroui-pro/react/chart-tooltip` * `@heroui-pro/react/code-block` * `@heroui-pro/react/markdown` * `@heroui-pro/react/sidebar` * …… ## 子路径列表 [#子路径列表] 以下是目前所有可用的子路径导入： | 子路径 | 组件 | | ----------------------- | ------------------- | | `action-bar` | ActionBar | | `agenda` | Agenda | | `app-layout` | AppLayout | | `area-chart` | AreaChart | | `bar-chart` | BarChart | | `carousel` | Carousel | | `cell-color-picker` | CellColorPicker | | `cell-select` | CellSelect | | `cell-slider` | CellSlider | | `cell-switch` | CellSwitch | | `chain-of-thought` | ChainOfThought | | `chart-tooltip` | ChartTooltip | | `chat-attachment` | ChatAttachment | | `chat-conversation` | ChatConversation | | `chat-list-view` | ChatListView | | `chat-loader` | ChatLoader | | `chat-message` | ChatMessage | | `chat-message-actions` | ChatMessageActions | | `chat-source` | ChatSource | | `chat-tool` | ChatTool | | `checkbox-button-group` | CheckboxButtonGroup | | `code-block` | CodeBlock | | `command` | Command | | `composed-chart` | ComposedChart | | `context-menu` | ContextMenu | | `data-grid` | DataGrid | | `drop-zone` | DropZone | | `emoji-picker` | EmojiPicker | | `emoji-reaction-button` | EmojiReactionButton | | `empty-state` | EmptyState | | `file-tree` | FileTree | | `floating-toc` | FloatingToc | | `hover-card` | HoverCard | | `inline-select` | InlineSelect | | `item-card` | ItemCard | | `item-card-group` | ItemCardGroup | | `kanban` | Kanban | | `kpi` | KPI | | `kpi-group` | KPIGroup | | `line-chart` | LineChart | | `list-view` | ListView | | `markdown` | Markdown | | `native-select` | NativeSelect | | `navbar` | Navbar | | `number-stepper` | NumberStepper | | `number-value` | NumberValue | | `pie-chart` | PieChart | | `pressable-feedback` | PressableFeedback | | `prompt-input` | PromptInput | | `prompt-suggestion` | PromptSuggestion | | `radar-chart` | RadarChart | | `radial-chart` | RadialChart | | `radio-button-group` | RadioButtonGroup | | `rating` | Rating | | `resizable` | Resizable | | `segment` | Segment | | `sheet` | Sheet | | `sidebar` | Sidebar | | `stepper` | Stepper | | `text-shimmer` | TextShimmer | | `trend-chip` | TrendChip | | `widget` | Widget | # Shadcn 清理记录 (/docs/other/shadcn-cleanup-summary) # Shadcn 清理记录 [#shadcn-清理记录] 项目从 shadcn 迁移至 HeroUI，以下为完整清理内容。 ## 一、packages/ui — 移除 shadcn 组件包 [#一packagesui--移除-shadcn-组件包] ### 删除的文件结构 [#删除的文件结构] ### 保留文件 [#保留文件] | 路径 | 说明 | | ------------------------ | ---------------------------------------- | | `src/styles/globals.css` | 仅含 `@import "tailwindcss"` + HeroUI 样式导入 | | `src/index.ts` | 空文件，供 tsc 通过 | ### 移除的依赖 [#移除的依赖] 从 `packages/ui/package.json` 移除： ``` shadcn, @base-ui/react, class-variance-authority, clsx, tailwind-merge, lucide-react, sonner, tw-animate-css, next-themes ``` `lucide-react` 从 packages/ui 移除仅因为该包已无组件文件。它仍保留在 `apps/web/package.json` 中（`loader.tsx` 在用），且 HeroUI 生态后续也可能用到，不做删除。 *** ## 二、apps/web — 移除使用 shadcn 的页面和组件 [#二appsweb--移除使用-shadcn-的页面和组件] ### 删除的文件结构 [#删除的文件结构-1] ### 保留文件 [#保留文件-1] | 路径 | 说明 | | ------------------------------------ | --------------------- | | `src/components/area-chart-demo.tsx` | 使用 HeroUI Pro，不受影响 | | `src/components/loader.tsx` | 仅用 lucide-react，不受影响 | | `src/routes/index.tsx` | 首页，引用 area-chart-demo | ### \_\_root.tsx 变更 [#__roottsx-变更] | 操作 | 内容 | | -- | --------------------------------------------------------------------- | | 移除 | `Toaster` (sonner)、`ThemeProvider` (next-themes)、`Header`、`trpc` 类型引用 | | 保留 | `HeadContent`、`Outlet`、`TanStackRouterDevtools`、`ReactQueryDevtools` | ### utils/trpc.ts 变更 [#utilstrpcts-变更] `toast.error(...)` 替换为 `console.error(...)`，sonner 移除后的临时替代。 ### 移除的依赖 [#移除的依赖-1] 从 `apps/web/package.json` 移除： ``` sonner, next-themes, embla-carousel, embla-carousel-react, tailwind-merge ``` *** ## 三、根目录 — 清理 catalog [#三根目录--清理-catalog] `package.json` 的 `workspaces.catalog` 移除了 `next-themes: "^0.4.6"`，整个 monorepo 已无引用。 **什么是 catalog？** Bun workspace 的集中版本管理机制。子包用 `"catalog:"` 引用声明好的版本号，避免各写一遍。仅当整个 monorepo 无人使用时才从 catalog 删除。 *** ## 四、配置清理 [#四配置清理] | 文件 | 变更 | | --------------------------- | ------------------------------------------------ | | `packages/ui/tsconfig.json` | 移除 `@my-better-t-app/ui/*` path mapping | | `apps/web/tsconfig.json` | 移除 `@my-better-t-app/ui/*` path mapping，保留 `@/*` | | `apps/web/components.json` | 删除 | *** ## 五、验证 [#五验证] 安装依赖 ```bash bun install ``` 构建验证 ```bash vite build ``` 确认无残留 ```bash grep -rn "shadcn\|@my-better-t-app/ui/components\|next-themes\|sonner" \ apps/web/src/ packages/ui/src/ # 返回空 ``` # 官方包审计 (/docs/security/audit-report) > 本文由 GLM-5-turbo 驱动的 CC 生成，内容基于项目源码与运行时记忆。 ## 审计范围 [#审计范围] | 包名 | 版本 | 类型 | | ------------------- | ------------ | ------------------------------- | | `heroui-pro` | 1.0.0-beta.9 | CLI 工具 + 认证/CDN/缓存共享库 | | `@heroui-pro/react` | 1.0.0-beta.3 | React Pro 组件（空壳，postinstall 下载） | | `heroui-native-pro` | 1.0.0-beta.3 | React Native Pro 组件（同上） | ## 核心结论 [#核心结论] **未发现第三方遥测 SDK，未发现主动数据窃取行为。** 这是一个付费组件库的商业授权与分发系统。 ## 混淆与反混淆 [#混淆与反混淆] 5 个文件使用 RC4 + base64 混淆，共 327 个加密字符串全部自动化解密成功。 已反混淆的文件： | 文件 | 说明 | | ------------------------------ | -------- | | `consts.deobfuscated.js` | 常量定义 | | `auth/keyring.deobfuscated.js` | 密钥环操作 | | `auth/session.deobfuscated.js` | 会话管理 | | `auth/ci.deobfuscated.js` | CI 认证流程 | | `cdn/download.deobfuscated.js` | CDN 下载逻辑 | 反混淆结果保存在 `heroui-pro-analysis/` 目录中。 ## 隐式追踪机制 [#隐式追踪机制] 虽然没有第三方遥测 SDK，但存在以下隐式追踪能力： ### 1. 项目指纹 [#1-项目指纹] 每次请求头发送 `X-HeroUI-Project: sha256(projectName).slice(0, 16)`，服务端可据此统计唯一项目数。 ### 2. 客户端标识 [#2-客户端标识] * `User-Agent: heroui-pro-cli/1.0.0-beta.4` * `X-HeroUI-Client-Version` header ### 3. 认证身份 [#3-认证身份] GitHub handle + JWT token 关联每次下载请求，可追踪单个用户的使用模式。 ### 4. 动态代码投递 [#4-动态代码投递] npm 包本身是空壳，实际组件代码通过 postinstall 从远端服务器拉取。这意味着： * 无法通过 npm 版本锁定来固定代码 * 每次安装的实际代码可能不同 * 上游可以随时更改分发的代码内容 ## 外部通信 [#外部通信] | 目标 | 用途 | 认证信息 | | -------------------- | --------- | ----------------------- | | `api.heroui.pro` | 认证、CDN 下载 | GitHub token / CI token | | `registry.npmjs.org` | 版本检查 | 无（3 秒超时） | | GitHub OAuth | SSE 回调 | GitHub OAuth token | ## 本地存储 [#本地存储] | 路径 | 内容 | 权限 | | --------------------------------------- | ------------------- | ---- | | `~/.config/heroui-pro/credentials.json` | GitHub handle + JWT | 0600 | | 系统密钥环 (libsecret) | 同上（如可用则优先） | — | | `~/.heroui/cache///` | 组件缓存 | — | 凭据文件使用 0600 权限（仅所有者可读写）。 ## 风险评估 [#风险评估] | 风险 | 级别 | 说明 | | ------ | -- | ------------------------ | | 动态代码投递 | 中 | npm 包为空壳，实际代码由上游控制 | | 项目指纹追踪 | 低 | 仅发送项目名哈希，非用户身份信息 | | 认证关联 | 低 | 使用 GitHub 身份，对付费产品属于正常行为 | | 本地凭据存储 | 低 | 使用标准 0600 权限 + 系统密钥环 | # 隐私与数据收集 (/docs/security/privacy) > 本文由 GLM-5-turbo 驱动的 CC 生成，内容基于项目源码与运行时记忆。 ## hpsetup 本身 [#hpsetup-本身] hpsetup CLI 工具**不主动收集任何用户数据**。它是一个纯粹的安装工具，职责是下载和安装 HeroUI Pro 组件。 hpsetup 的所有外部通信： | 目标 | 请求 | 发送的数据 | | ------------------------ | ----------------------- | ------- | | `hpsetup-cdn.932324.xyz` | GET `/api/tarball/...` | API Key | | `registry.npmjs.org` | GET `/{package}/latest` | 无认证信息 | ### API Key 用途 [#api-key-用途] API Key 仅用于 CF Worker 的认证，以验证用户是否有权下载 tarball。Key 的格式为 `hp_` + 48 位十六进制字符，由管理员通过 Admin API 创建。 ## 上游依赖（heroui-pro） [#上游依赖heroui-pro] hpsetup 安装的 `heroui-pro` 包（npm 空壳）在 postinstall 阶段会与上游 `api.heroui.pro` 通信。以下数据收集行为来自上游，不属于 hpsetup 本身： ### 收集的数据 [#收集的数据] | 数据 | 来源 | 用途 | | ------------- | -------------------------- | --------- | | GitHub handle | OAuth 认证 | 用户身份识别与授权 | | JWT token | 认证响应 | 会话管理 | | 项目名哈希 | `package.json` 的 `name` 字段 | 唯一项目统计 | | CLI 版本 | User-Agent header | 版本分布统计 | ### 不收集的数据 [#不收集的数据] * 源代码内容 * 文件系统结构（除 `package.json` 的 `name`） * 环境变量 * 系统信息 ## 缓存与本地存储 [#缓存与本地存储] | 存储 | 内容 | 位置 | | ---------- | ------------------- | --------------------------------------- | | tarball 缓存 | 组件压缩包 | `~/.heroui/cache/` | | 凭据 | GitHub handle + JWT | `~/.config/heroui-pro/credentials.json` | | 凭据（备选） | 同上 | 系统密钥环 (libsecret) | 所有凭据文件使用 0600 权限。清除缓存和凭据： ```bash rm -rf ~/.heroui/cache rm -rf ~/.config/heroui-pro ``` ## 网络请求汇总 [#网络请求汇总] 一次完整的 hpsetup 安装流程涉及的网络请求： ``` 1. CLI → registry.npmjs.org 版本检查（无认证） 2. CLI → hpsetup-cdn.932324.xyz 下载 tarball（API Key 认证） 3. [可选] heroui-pro → api.heroui.pro postinstall 认证（上游行为） ``` 步骤 3 仅在 `heroui-pro` 包的 postinstall 脚本执行时发生，属于上游包的独立行为。 # 快速开始 (/docs/web/quick-start) > 本文由人工撰写（md），AI 优化（mdx）。 优先推荐使用 pnpm，因为它最早进行测试，覆盖的场景更多一些。 其他的包管理器也在路上，测试完成后会更新、完善文档。 ## 一步到位 [#一步到位] 跳过手动安装的项目准备、安装 HeroUI Pro、引入 demo 组件等过程，一步到位。 克隆[模板](https://github.com/rhywonfeong/hp-nextjs-app-template) ```bash npx -y degit rhywonfeong/hp-nextjs-app-template my-hp-nextjs-app cd my-hp-nextjs-app ``` `degit` 会克隆仓库，但丢弃远程的 git 历史。 确保已安装 [p cli](https://github.com/ru-yaka/p)，然后在任意路径下执行： ```bash p clone --degit rhywonfeong/hp-nextjs-app-template my-hp-nextjs-app ``` 它会以 degit 模式克隆远程仓库，放到统一的项目目录下（方便管理），并用 IDE 打开（默认 cursor）。 安装依赖 ```bash npm install ``` ```bash pnpm install ``` ```bash bun install ``` ```bash yarn install ``` 运行 hpsetup 安装 HeroUI Pro 我这里是开发测试，所以用的是 beta 版本，大家不要用 beta 版本哈（可能有更多的 bug），一般用 latest 版本就好。 另外，这里是从本地缓存中恢复了（同一版本的依赖包固定，官方也会缓存）。如果本地缓存中没有的话，会从 CDN 拉取。 启动预览 ```bash npm run dev ``` ```bash pnpm dev ``` ```bash bun dev ``` ```bash yarn dev ``` ## 手动安装 [#手动安装] ### 项目准备 [#项目准备] 创建项目 首先，得有一个 HeroUI 项目。 如果是从零开始的新项目，可以用 [heroui-cli](https://www.npmjs.com/package/heroui-cli) 进行初始化： ```bash npx -y heroui-cli@latest init my-heroui-app ``` 上边这个命令在哪个目录下运行，项目就会放在哪个目录下。如果希望在任意目录下运行，还能实现统一管理，可以试试 [p cli](https://github.com/ru-yaka/p)（请确保提前安装）： ```bash p new -- npx -y heroui-cli@latest init my-heroui-app ``` 它会把项目放到统一的项目目录（`~/.p/projects/`），然后用 IDE（可配，默认 cursor）打开。 另外，还可以直接克隆现有的模板（无需交互）： ```bash npx -y degit rhywonfeong/heroui-nextjs-app-template my-heroui-nextjs-app ``` 安装依赖 ```bash npm install ``` ```bash pnpm install ``` ```bash bun install ``` ```bash yarn install ``` 验证运行 启动开发服务器，确认项目可以正常运行： ```bash npm run dev ``` ```bash pnpm run dev ``` ```bash bun run dev ``` ```bash yarn dev ``` 验证运行 确认页面正常显示后，按 `Ctrl+C` 停止开发服务器。 初始化 Git（可选） 建议在安装 HeroUI Pro 之前先提交一次，方便查看之后做了哪些变更： ```bash git init && git add . && git commit -m "init: heroui project" ``` ```bash git init; git add .; git commit -m "init: heroui project" ``` ### 安装 HeroUI Pro [#安装-heroui-pro] 运行 hpsetup image-20260521173332176 引入样式 在你的全局 CSS 文件末尾新增一行： ```css title="styles/globals.css" @import "tailwindcss"; /* [!code ++] */ @import "@heroui/styles"; /* [!code ++] */ @import "@heroui-pro/react/css"; ``` ```css title="src/styles/globals.css" @import "tailwindcss"; /* [!code ++] */ @import "@heroui/styles"; /* [!code ++] */ @import "@heroui-pro/react/css"; ``` ```css title="styles/globals.css" @import "tailwindcss"; /* [!code ++] */ @import "@heroui/styles"; /* [!code ++] */ @import "@heroui-pro/react/css"; ``` ### 引入 demo 组件 [#引入-demo-组件] 创建组件 ```tsx title="components/area-chart-demo.tsx" "use client"; import {Card} from "@heroui/react"; import { ChartTooltip } from "@heroui-pro/react/chart-tooltip"; import {AreaChart} from "@heroui-pro/react/area-chart"; const revenueData = [ {month: "Jan", revenue: 4200}, {month: "Feb", revenue: 5800}, {month: "Mar", revenue: 4900}, {month: "Apr", revenue: 7200}, {month: "May", revenue: 6100}, {month: "Jun", revenue: 8400}, {month: "Jul", revenue: 7800}, {month: "Aug", revenue: 9200}, {month: "Sep", revenue: 8600}, {month: "Oct", revenue: 10200}, {month: "Nov", revenue: 9800}, {month: "Dec", revenue: 11500}, ]; export default function AreaChartDemo() { return ( Monthly Revenue `$${(v / 1000).toFixed(0)}k`} width={40} /> { if (!active || !payload?.length) return null; return ( {label} {payload.map((entry) => ( {entry.name} ${Number(entry.value).toLocaleString()} ))} ); }} /> ); } ``` ```tsx title="src/components/area-chart-demo.tsx" "use client"; import {Card} from "@heroui/react"; import { ChartTooltip } from "@heroui-pro/react/chart-tooltip"; import {AreaChart} from "@heroui-pro/react/area-chart"; const revenueData = [ {month: "Jan", revenue: 4200}, {month: "Feb", revenue: 5800}, {month: "Mar", revenue: 4900}, {month: "Apr", revenue: 7200}, {month: "May", revenue: 6100}, {month: "Jun", revenue: 8400}, {month: "Jul", revenue: 7800}, {month: "Aug", revenue: 9200}, {month: "Sep", revenue: 8600}, {month: "Oct", revenue: 10200}, {month: "Nov", revenue: 9800}, {month: "Dec", revenue: 11500}, ]; export default function AreaChartDemo() { return ( Monthly Revenue `$${(v / 1000).toFixed(0)}k`} width={40} /> { if (!active || !payload?.length) return null; return ( {label} {payload.map((entry) => ( {entry.name} ${Number(entry.value).toLocaleString()} ))} ); }} /> ); } ``` ```tsx title="components/area-chart-demo.tsx" "use client"; import {Card} from "@heroui/react"; import { ChartTooltip } from "@heroui-pro/react/chart-tooltip"; import {AreaChart} from "@heroui-pro/react/area-chart"; const revenueData = [ {month: "Jan", revenue: 4200}, {month: "Feb", revenue: 5800}, {month: "Mar", revenue: 4900}, {month: "Apr", revenue: 7200}, {month: "May", revenue: 6100}, {month: "Jun", revenue: 8400}, {month: "Jul", revenue: 7800}, {month: "Aug", revenue: 9200}, {month: "Sep", revenue: 8600}, {month: "Oct", revenue: 10200}, {month: "Nov", revenue: 9800}, {month: "Dec", revenue: 11500}, ]; export default function AreaChartDemo() { return ( Monthly Revenue `$${(v / 1000).toFixed(0)}k`} width={40} /> { if (!active || !payload?.length) return null; return ( {label} {payload.map((entry) => ( {entry.name} ${Number(entry.value).toLocaleString()} ))} ); }} /> ); } ``` 引入页面 ```tsx title="app/page.tsx" import AreaChartDemo from "@/components/area-chart-demo"; export default function Page() { return ; } ``` ```tsx title="src/App.tsx" import AreaChartDemo from "./components/area-chart-demo"; export default function Page() { return ; } ``` ```tsx title="pages/index.tsx" import AreaChartDemo from "../components/area-chart-demo"; export default function Page() { return ; } ``` 启动预览 ```bash npm run dev ``` ```bash pnpm dev ``` ```bash bun dev ``` ```bash yarn dev ``` 启动预览 ## 常见问题 [#常见问题] ### HeroUI CLI 选项说明 [#heroui-cli-选项说明] HeroUI CLI 初始化选项 注意哈，HeroUI CLI 新建项目的时候会有三个选项： * 第 1、2 个选项都是 Next.js，第 3 个选项是 React + Vite * 其中第 2 个选项是 Next.js Pages Router，这个是为了兼容老项目的，现在已经不推荐使用了，新项目都推荐用 App Router（第一个选项） ### 安装报错 [#安装报错] 如果在 install 安装的时候报 `[ERR_PNPM_IGNORED_BUILDS]` 这个错误，我们需要同意构建，也就是允许这些依赖的构建脚本运行，然后才能继续。 pnpm approve-builds 运行： ```bash pnpm approve-builds ```