# @carefully-built/saas-kit 中文文档

规范地址：https://npmcn.com/package/%40carefully-built/saas-kit/

版本：0\.1\.47
npm 元数据更新时间：2026-11-06T17:29:21.278Z
中文译文更新时间：2026-11-09T05:50:44.781Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40carefully-built/saas-kit
原文对照：https://npmcn.com/package/%40carefully-built/saas-kit/?lang=original
项目主页：https://github.com/AlessandroDodi/carefully-built-saas-kit#readme
源码仓库：https://github.com/AlessandroDodi/carefully-built-saas-kit

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：37.4 kB，108 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：35 个
- peer 依赖：zod \>=4\.0\.0，clsx \>=2\.0\.0，next \>=15\.0\.0 \|\| \>=16\.0\.0，nuqs \>=2\.0\.0，vaul \>=1\.0\.0，react ^18\.0\.0 \|\| ^19\.0\.0，convex \>=1\.0\.0，sonner \>=1\.0\.0 \|\| \>=2\.0\.0，date-fns \>=4\.0\.0，radix-ui \>=1\.0\.0，recharts \>=2\.0\.0，papaparse ^5\.0\.0，react-dom ^18\.0\.0 \|\| ^19\.0\.0，lucide-react \>=0\.400\.0 \|\| \>=1\.0\.0，@tiptap/react \>=3\.0\.0，@xyflow/react ^12\.10\.2，tailwind-merge \>=2\.0\.0 \|\| \>=3\.0\.0，react-hook-form \>=7\.0\.0，react-day-picker \>=9\.0\.0，@fullcalendar/core ^6\.1\.0，react-country-flag \>=3\.0\.0，@fullcalendar/react ^6\.1\.0，@hookform/resolvers \>=5\.0\.0，@tiptap/starter-kit \>=3\.0\.0，@radix-ui/react-slot ^1\.0\.0，@fullcalendar/daygrid ^6\.1\.0，@fullcalendar/timegrid ^6\.1\.0，@tiptap/extension-link \>=3\.0\.0，@tiptap/extension-table \>=3\.0\.0，class-variance-authority \>=0\.7\.0，react-phone-number-input \>=3\.0\.0，@fullcalendar/interaction ^6\.1\.0，@tiptap/extension-table-row \>=3\.0\.0，@tiptap/extension-table-cell \>=3\.0\.0，@tiptap/extension-table-header \>=3\.0\.0
- 首次发布：2026-06-23T19:32:07.691Z
- 最新版本发布：2026-11-06T17:29:21.081Z
- 近 30 天下载量：5831（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：47（近 12 个月 47 个）

## 中文简介

1-install小心地为React,Next.js,Convex,WorkOS以及可编辑的SaaS组件构建了SaaS Kit包.

## 安装

```sh
npm install @carefully-built/saas-kit
```

也可以使用：`pnpm add @carefully-built/saas-kit`、`yarn add @carefully-built/saas-kit`、`bun add @carefully-built/saas-kit`

## README

# @ 精心建造/ saas- kit

一个安装用于精心建造的SaaS组件、产品表面和帮助者.

精心建造SaaS Kit是存在的,所以每一个新的B2B产品都不必从零开始重塑相同的表格,表格,过滤器,工作表,设置,文件,通知,日历和仪表板模式.

如果您想要管理 npm 导入和共享应用程序的升级, 请使用此软件包 。 使用 `@carefully-built/cli` 当您想要从可编辑组件源中弹出到应用程序时.

## 组件预览

![Smart Table](https://raw.githubusercontent.com/AlessandroDodi/carefully-built-saas-kit/main/docs/saas-kit/images/smarttable.png) ![Responsive Sheet](https://raw.githubusercontent.com/AlessandroDodi/carefully-built-saas-kit/main/docs/saas-kit/images/responsivesheet.png) ![Kanban](https://raw.githubusercontent.com/AlessandroDodi/carefully-built-saas-kit/main/docs/saas-kit/images/kanban.png) ![Charts](https://raw.githubusercontent.com/AlessandroDodi/carefully-built-saas-kit/main/docs/saas-kit/images/charts.png) ![Notifications](https://raw.githubusercontent.com/AlessandroDodi/carefully-built-saas-kit/main/docs/saas-kit/images/notifications.png) ![Search](https://raw.githubusercontent.com/AlessandroDodi/carefully-built-saas-kit/main/docs/saas-kit/images/search.png) ![Calendar](https://raw.githubusercontent.com/AlessandroDodi/carefully-built-saas-kit/main/docs/saas-kit/images/calendar.png) ![Maps](https://raw.githubusercontent.com/AlessandroDodi/carefully-built-saas-kit/main/docs/saas-kit/images/maps.png) ![Superadmin](https://raw.githubusercontent.com/AlessandroDodi/carefully-built-saas-kit/main/docs/saas-kit/images/superadmin.png) ![Widgets](https://raw.githubusercontent.com/AlessandroDodi/carefully-built-saas-kit/main/docs/saas-kit/images/widgets.png) ![Files](https://raw.githubusercontent.com/AlessandroDodi/carefully-built-saas-kit/main/docs/saas-kit/images/file-dropper.png) ![Theme](https://raw.githubusercontent.com/AlessandroDodi/carefully-built-saas-kit/main/docs/saas-kit/images/theme-switcher.png)

## 安装

```bash
bun add @carefully-built/saas-kit
```

```tsx
import { Button, SmartTable, TableToolbar, ResponsiveSheet } from "@carefully-built/saas-kit";
```

套件包括模块化的小心构建套件作为依赖性. 您的应用程序仍应安装它实际使用的框架对等依赖, 如 React, Next.js, Convex, WorkOS, Radix原始语, React Hook Form, TipTap, FullCalendar, 以及 Recharts.

## 软件包模块

从根部导入共享的UI原始物,或者从子路径导入一个产品区域.

| 模块 | 用于 |
| --- | --- |
| `@carefully-built/saas-kit` | 共享的 UI 原始文件、 表格工具、 覆盖、 空状态、 错误页、 钩和工具 |
| `@carefully-built/saas-kit/agenda` | 日历和议程表面 |
| `@carefully-built/saas-kit/app-shell` | 板壳、响应导航、页面布局和移动底导航 |
| `@carefully-built/saas-kit/association-picker` | 可搜索关联选择 |
| `@carefully-built/saas-kit/auth-pages` | 认证表单、控制器、页面、社会登录、组织、和 WorkOS 认证 UI |
| `@carefully-built/saas-kit/automations` | 自动化构建器状态、画布、选项和草稿帮助器 |
| `@carefully-built/saas-kit/charts` | 剪贴板图表部件 |
| `@carefully-built/saas-kit/convex-crud` | CRUD 辅助器 |
| `@carefully-built/saas-kit/convex-multitenant` | Convex 多重租赁助手 |
| `@carefully-built/saas-kit/convex-platform` | Convex 平台关联助手 |
| `@carefully-built/saas-kit/convex-workos` | Convex WorkOS 集成辅助工具 |
| `@carefully-built/saas-kit/crud` | CRUD 表格/页面状态和 URL 过滤器 |
| `@carefully-built/saas-kit/custom-fields` | 自定义和输入 |
| `@carefully-built/saas-kit/files` | 文档卡、网格、上传和文件过滤 |
| `@carefully-built/saas-kit/forms` | Schema/ 客户表和用户拾取字段 |
| `@carefully-built/saas-kit/import-export` | CSV 进出口助手和工作表 |
| `@carefully-built/saas-kit/kanban` | Kanban 板和管线助手 |
| `@carefully-built/saas-kit/legal-ui` | 法律文件渲染器和缺省法律文本 |
| `@carefully-built/saas-kit/maps-ui` | 谷歌地图 |
| `@carefully-built/saas-kit/notes` | 注解 CRUD 页和注解列表类型 |
| `@carefully-built/saas-kit/notifications` | 通知列表、按钮和可视元数据 |
| `@carefully-built/saas-kit/resource-kit` | 资源页面、 实体细节 shells、 相关标签和土司助手 |
| `@carefully-built/saas-kit/rich-text` | 丰富的文本编辑器和渲染器 |
| `@carefully-built/saas-kit/search` | 搜索和命令调色板模块 |
| `@carefully-built/saas-kit/settings-ui` | 设置牌和设置标签表面 |
| `@carefully-built/saas-kit/superadmin` | 超级admin UI, 服务器助手和 Next.js 页面厂 |
| `@carefully-built/saas-kit/theme-ui` | 主题选择器组件 |
| `@carefully-built/saas-kit/ui` | 直接接入UI包桶 |
| `@carefully-built/saas-kit/user-picker` | 用户拾件桶 |
| `@carefully-built/saas-kit/widgets` | 剪贴板部件包装器 |
| `@carefully-built/saas-kit/workos` | WorkOS 组织 UI 和服务器助手 |
| `@carefully-built/saas-kit/server` | 仅限服务器的助手 |
| `@carefully-built/saas-kit/next` | Next.js 帮助者 |

子路径导入示例 :

```tsx
import { DashboardPageLayout } from "@carefully-built/saas-kit/app-shell";
import { AuthLoginPage } from "@carefully-built/saas-kit/auth-pages/pages";
import { createWorkOSWidgetTokenResponse } from "@carefully-built/saas-kit/server";
import { createSuperAdminPage } from "@carefully-built/saas-kit/next";
```

## UI 完整登记

每个公用UI模块导出 `@carefully-built/ui` 可通过 `@carefully-built/saas-kit` 和通过CLI登记.

| 书记官处条目 | 管理导入 | 可编辑源 |
| --- | --- | --- |
| `avatar` | `import { Avatar, AvatarFallback, AvatarImage } from "@carefully-built/saas-kit"` | `bunx @carefully-built/cli add avatar` |
| `button` | `import { Button, ButtonSize, ButtonVariant, buttonVariants } from "@carefully-built/saas-kit"` | `bunx @carefully-built/cli add button` |
| `calendar` | `import { Calendar } from "@carefully-built/saas-kit"` | `bunx @carefully-built/cli add calendar` |
| `card` | `import { Card, CardContent, CardDescription, CardFooter, CardHeader, CardTitle } from "@carefully-built/saas-kit"` | `bunx @carefully-built/cli add card` |
| `chip` | `import { Chip, ChipButton } from "@carefully-built/saas-kit"` | `bunx @carefully-built/cli add chip` |
| `chip-utils` | `import { CHIP_CLASS_NAMES, ChipSize, getChipClassName } from "@carefully-built/saas-kit"` | `bunx @carefully-built/cli add chip-utils` |
| `date-display` | `import { DateDisplayValue, formatAbsoluteDate, formatDisplayDate } from "@carefully-built/saas-kit"` | `bunx @carefully-built/cli add date-display` |
| `dialog` | `import { Dialog, DialogContent, DialogDescription, DialogFooter, DialogHeader, DialogOverlay } from "@carefully-built/saas-kit"` | `bunx @carefully-built/cli add dialog` |
| `display-date` | `import { DisplayDate } from "@carefully-built/saas-kit"` | `bunx @carefully-built/cli add display-date` |
| `drawer` | `import { Drawer, DrawerContent, DrawerDescription, DrawerHeader, DrawerOverlay, DrawerPortal } from "@carefully-built/saas-kit"` | `bunx @carefully-built/cli add drawer` |
| `dropdown-menu` | `import { DropdownMenu, DropdownMenuCheckboxItem, DropdownMenuContent, DropdownMenuItem, DropdownMenuLabel, DropdownMenuSeparator } from "@carefully-built/saas-kit"` | `bunx @carefully-built/cli add dropdown-menu` |
| `empty-state` | `import { CollectionEmptyState, EmptyStateCard, InitialEmptyState, NoResultsState, ResolveCollectionEmptyStateOptions, resolveCollectionEmptyState } from "@carefully-built/saas-kit"` | `bunx @carefully-built/cli add empty-state` |
| `error-page` | `import { ErrorCode, ErrorPageContent, ErrorPageKind, PostHogErrorCapturePayload, ResolveErrorPageContentOptions, SaasErrorPage } from "@carefully-built/saas-kit"` | `bunx @carefully-built/cli add error-page` |
| `field-detail-row` | `import { FieldDetailRow } from "@carefully-built/saas-kit"` | `bunx @carefully-built/cli add field-detail-row` |
| `file-dropzone` | `import { FileDropzone } from "@carefully-built/saas-kit"` | `bunx @carefully-built/cli add file-dropzone` |
| `help-info-button` | `import { HelpInfoButton } from "@carefully-built/saas-kit"` | `bunx @carefully-built/cli add help-info-button` |
| `input` | `import { Input } from "@carefully-built/saas-kit"` | `bunx @carefully-built/cli add input` |
| `keyboard-shortcut-hint` | `import { KeyboardKeycap, ShortcutModifierKeycap } from "@carefully-built/saas-kit"` | `bunx @carefully-built/cli add keyboard-shortcut-hint` |
| `label` | `import { Label } from "@carefully-built/saas-kit"` | `bunx @carefully-built/cli add label` |
| `pagination` | `import { Pagination } from "@carefully-built/saas-kit"` | `bunx @carefully-built/cli add pagination` |
| `popover` | `import { Popover, PopoverContent, PopoverTrigger } from "@carefully-built/saas-kit"` | `bunx @carefully-built/cli add popover` |
| `responsive-sheet` | `import { ResponsiveSheet, SheetOutsideInteractionGuard } from "@carefully-built/saas-kit"` | `bunx @carefully-built/cli add responsive-sheet` |
| `responsive-sheet.footer` | `import { DesktopConfirmShortcutHint, SheetActionFooter } from "@carefully-built/saas-kit"` | `bunx @carefully-built/cli add responsive-sheet.footer` |
| `responsive-sheet.shortcuts` | `import { getDesktopShortcutModifierLabel, isAllowedConfirmShortcutEvent, useDesktopConfirmShortcut, useDesktopShortcutModifierLabel } from "@carefully-built/saas-kit"` | `bunx @carefully-built/cli add responsive-sheet.shortcuts` |
| `scroll-fade-area` | `import { ScrollFadeArea } from "@carefully-built/saas-kit"` | `bunx @carefully-built/cli add scroll-fade-area` |
| `search` | `import { SearchTextPart, buildSearchText, filterAndRankBySearch, rankBySearch, scoreFuzzyMatch } from "@carefully-built/saas-kit"` | `bunx @carefully-built/cli add search` |
| `searchable-select` | `import { AUTO_SEARCHABLE_SELECT_THRESHOLD, SearchableSelect, SearchableSelectOption, getSearchableSelectPortalContainer, isSearchableSelectPointerInside } from "@carefully-built/saas-kit"` | `bunx @carefully-built/cli add searchable-select` |
| `searchable-select-position` | `import { SearchableSelectRect, resolveSearchableSelectDropdownPosition } from "@carefully-built/saas-kit"` | `bunx @carefully-built/cli add searchable-select-position` |
| `segmented-toggle` | `import { SegmentedToggle, SegmentedToggleOption } from "@carefully-built/saas-kit"` | `bunx @carefully-built/cli add segmented-toggle` |
| `select` | `import { Select, SelectContent, SelectItem, SelectScrollDownButton, SelectScrollUpButton, SelectTrigger } from "@carefully-built/saas-kit"` | `bunx @carefully-built/cli add select` |
| `sheet` | `import { Sheet, SheetContent, SheetDescription, SheetHeader, SheetTitle } from "@carefully-built/saas-kit"` | `bunx @carefully-built/cli add sheet` |
| `skeleton` | `import { Skeleton } from "@carefully-built/saas-kit"` | `bunx @carefully-built/cli add skeleton` |
| `smart-table` | `import { ActionHandlers, ActionType, Column, ColumnAlign, PaginationConfig, SmartTable } from "@carefully-built/saas-kit"` | `bunx @carefully-built/cli add smart-table` |
| `switch` | `import { Switch } from "@carefully-built/saas-kit"` | `bunx @carefully-built/cli add switch` |
| `table` | `import { Table, TableBody, TableCaption, TableCell, TableFooter, TableHead } from "@carefully-built/saas-kit"` | `bunx @carefully-built/cli add table` |
| `table-toolbar` | `import { CustomTableToolbarFilter, FilterConfig, FilterDropdown, FilterOption, SearchInput, TableToolbar } from "@carefully-built/saas-kit"` | `bunx @carefully-built/cli add table-toolbar` |
| `tabs` | `import { Tabs, TabsContent, TabsList, TabsScrollArea, TabsTrigger, tabsListVariants } from "@carefully-built/saas-kit"` | `bunx @carefully-built/cli add tabs` |
| `textarea` | `import { Textarea } from "@carefully-built/saas-kit"` | `bunx @carefully-built/cli add textarea` |
| `tooltip` | `import { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger } from "@carefully-built/saas-kit"` | `bunx @carefully-built/cli add tooltip` |
| `use-media-query` | `import { useIsMobile, useMediaQuery } from "@carefully-built/saas-kit"` | `bunx @carefully-built/cli add use-media-query` |
| `user-picker` | `import { UserPicker } from "@carefully-built/saas-kit"` | `bunx @carefully-built/cli add user-picker` |
| `user-picker-utils` | `import { UserPickerCopy, UserPickerOption, buildUserInitials, filterSelectableUsers, filterUsersBySearch, formatSelectedUserSummary } from "@carefully-built/saas-kit"` | `bunx @carefully-built/cli add user-picker-utils` |

一些条目从一个模块中导出多个相关的组件,钩子,帮助器,以及类型. TypeScript自动完成将在安装工具包后显示完整的API.

## 使用 CLI 可编辑源

当一个组件成为可以直接编辑的本地代码时使用 CLI .

```bash
bunx @carefully-built/cli list
bunx @carefully-built/cli add button
bunx @carefully-built/cli add smart-table
bunx @carefully-built/cli add responsive-sheet
```

CLI 复制组件源及其本地依赖性关闭到您的应用程序中 。 它读取了常见的影子项目公约,例如: `components.json` 别名和 `tsconfig.json` 路径.

## 导入 vs 弹出

从 `@carefully-built/saas-kit` 当:

-   您需要软件包更新和错误修正
-   组件应保持共享应用程序
-   特定产品的差异可以通过道具,槽来处理, `className`,或 `classes`

使用 `@carefully-built/cli add` 当:

-   组件需要本地产品行为
-   设计需要偏离共享软件包
-   您想要拥有并编辑消费应用程序中的每行
-   组件应当遵循应用程序的正常源控工作流程

## 复制和本地化

每一个用户界面字符串仍然是标签/配置道具. 默认跟随风筝语言:英语没有提供者,意大利语有 `KitLocaleProvider`数字 :

```tsx
import { KitLocaleProvider } from '@carefully-built/saas-kit';

<KitLocaleProvider locale="it">{children}</KitLocaleProvider>;
```

迄今本地化: `ui` (重叠、表格工具栏、可搜索选择、空和出错状态、文件投放区、用户拾取器), `forms` 字段,则, `auth-pages` (页数、表格、社会按钮、组织选择、法律同意、验证) `search` 命令调色板。 服务器侧认证动作消息保留在内 `config.messages`。 。 。 .

## 常见问题

### @carefully-built/saas-kit 是什么？

1-install小心地为React,Next\.js,Convex,WorkOS以及可编辑的SaaS组件构建了SaaS Kit包\.

### 如何安装 @carefully-built/saas-kit？

在项目目录运行 npm install @carefully-built/saas-kit，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：zod（\>=4\.0\.0）、clsx（\>=2\.0\.0）、next（\>=15\.0\.0 \|\| \>=16\.0\.0）、nuqs（\>=2\.0\.0）、vaul（\>=1\.0\.0）、react（^18\.0\.0 \|\| ^19\.0\.0）、convex（\>=1\.0\.0）、sonner（\>=1\.0\.0 \|\| \>=2\.0\.0）、date-fns（\>=4\.0\.0）、radix-ui（\>=1\.0\.0）、recharts（\>=2\.0\.0）、papaparse（^5\.0\.0）、react-dom（^18\.0\.0 \|\| ^19\.0\.0）、lucide-react（\>=0\.400\.0 \|\| \>=1\.0\.0）、@tiptap/react（\>=3\.0\.0）、@xyflow/react（^12\.10\.2）、tailwind-merge（\>=2\.0\.0 \|\| \>=3\.0\.0）、react-hook-form（\>=7\.0\.0）、react-day-picker（\>=9\.0\.0）、@fullcalendar/core（^6\.1\.0）、react-country-flag（\>=3\.0\.0）、@fullcalendar/react（^6\.1\.0）、@hookform/resolvers（\>=5\.0\.0）、@tiptap/starter-kit（\>=3\.0\.0）、@radix-ui/react-slot（^1\.0\.0）、@fullcalendar/daygrid（^6\.1\.0）、@fullcalendar/timegrid（^6\.1\.0）、@tiptap/extension-link（\>=3\.0\.0）、@tiptap/extension-table（\>=3\.0\.0）、class-variance-authority（\>=0\.7\.0）、react-phone-number-input（\>=3\.0\.0）、@fullcalendar/interaction（^6\.1\.0）、@tiptap/extension-table-row（\>=3\.0\.0）、@tiptap/extension-table-cell（\>=3\.0\.0）、@tiptap/extension-table-header（\>=3\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @carefully-built/saas-kit 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @carefully-built/saas-kit 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @carefully-built/saas-kit 可以商用吗？

@carefully-built/saas-kit 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @carefully-built/saas-kit 的下载量有多少？

根据 npm 官方下载统计，@carefully-built/saas-kit 在 2026/10/09 – 2026/11/07 这 30 天内被下载 5,831 次，日均约 194 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @carefully-built/saas-kit 还在维护吗？

最新版本 0\.1\.47 发布于 2026/11/07（2 天前）；至今共发布 47 个版本，其中过去 12 个月发布了 47 个；首次发布于 2026/06/24。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。