@carefully-built/saas-kit

@carefully-built/saas-kit

One install for Carefully Built SaaS components, product surfaces, and helpers.

Carefully Built SaaS Kit exists so every new B2B product does not have to reinvent the same tables, forms, filters, sheets, settings, files, notifications, calendars, and dashboard patterns from scratch.

Use this package when you want managed npm imports and shared upgrades across apps. Use @carefully-built/cli when you want to eject editable component source into an app.

Component Previews

Install

bun add @carefully-built/saas-kit

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

The package includes the modular Carefully Built packages as dependencies. Your app should still install the framework peer dependencies it actually uses, such as React, Next.js, Convex, WorkOS, Radix primitives, React Hook Form, TipTap, FullCalendar, and Recharts.

Package Modules

Import from the root for shared UI primitives, or from a subpath for a product area.

Module	Use for
@carefully-built/saas-kit	Shared UI primitives, table tools, overlays, empty states, error pages, hooks, and utilities
@carefully-built/saas-kit/agenda	Calendar and agenda surfaces
@carefully-built/saas-kit/app-shell	Dashboard shell, top route loader, responsive navigation, page layouts, and mobile bottom navigation
@carefully-built/saas-kit/association-picker	Searchable association selection
@carefully-built/saas-kit/auth-pages	Auth forms, controllers, pages, social login, organizations, and WorkOS auth UI
@carefully-built/saas-kit/automations	Automation builder state, canvas, options, and draft helpers
@carefully-built/saas-kit/charts	Dashboard chart widgets
@carefully-built/saas-kit/convex-crud	Convex CRUD helpers
@carefully-built/saas-kit/convex-multitenant	Convex multitenancy helpers
@carefully-built/saas-kit/convex-platform	Convex platform association helpers
@carefully-built/saas-kit/convex-workos	Convex WorkOS integration helpers
@carefully-built/saas-kit/crud	CRUD table/page state and URL filters
@carefully-built/saas-kit/custom-fields	Custom field definitions and inputs
@carefully-built/saas-kit/files	Document cards, grids, uploads, and file filtering
@carefully-built/saas-kit/forms	Schema/custom forms and user picker fields
@carefully-built/saas-kit/import-export	CSV import/export helpers and sheets
@carefully-built/saas-kit/kanban	Kanban board and pipeline helpers
@carefully-built/saas-kit/legal-ui	Legal document renderer and default legal text
@carefully-built/saas-kit/maps-ui	Google Maps Places loader helpers
@carefully-built/saas-kit/notes	Notes CRUD page and note list types
@carefully-built/saas-kit/notifications	Notification lists, buttons, and visual metadata
@carefully-built/saas-kit/resource-kit	Resource pages, entity detail shells, associated tabs, and toast helpers
@carefully-built/saas-kit/rich-text	Rich text editor and renderer
@carefully-built/saas-kit/search	Search and command palette modules
@carefully-built/saas-kit/settings-ui	Settings cards and settings tab surfaces
@carefully-built/saas-kit/superadmin	Superadmin UI, server helpers, and Next.js page factory
@carefully-built/saas-kit/theme-ui	Theme selector components
@carefully-built/saas-kit/ui	Direct access to the UI package barrel
@carefully-built/saas-kit/user-picker	User picker package barrel
@carefully-built/saas-kit/widgets	Dashboard widget wrappers
@carefully-built/saas-kit/workos	WorkOS organization UI and server helpers
@carefully-built/saas-kit/server	Server-only helpers
@carefully-built/saas-kit/next	Next.js helpers

Example subpath imports:

import { AppTopLoader, 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";

Full UI Registry

Every public UI module exported by @carefully-built/ui is available through @carefully-built/saas-kit and through the CLI registry.

Registry entry	Managed import	Editable source
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

Some entries export several related components, hooks, helpers, and types from one module. TypeScript autocomplete will show the full API after installing the kit.

Editable Source With The CLI

Use the CLI when a component should become local code that you can edit directly.

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

The CLI copies the component source and its local dependency closure into your app. It reads common shadcn project conventions such as components.json aliases and tsconfig.json paths.

Import vs Eject

Import from @carefully-built/saas-kit when:

• you want package updates and bug fixes
• the component should stay shared across apps
• product-specific differences can be handled with props, slots, className, or classes

Use @carefully-built/cli add when:

• the component needs local product behavior
• design needs to diverge from the shared package
• you want to own and edit every line in the consuming app
• the component should follow the app's normal source-control workflow

Copy And Localization

SaaS kit defaults are English. Italian or other localized apps should pass app-specific copy through the component label/config props. Components with user-facing copy are designed to expose labels or configuration objects so package defaults do not force one language across all apps.