SaaS dashboard

1. 1.

   Open your existing React project

   Use React 19+, TypeScript/TSX, and a working Tailwind CSS 4 build. Keep the project's existing router, dependencies, and global stylesheet.

2. 2.

   Check components.json before installing

   Reuse an existing components.json. Its aliases.components must resolve in TypeScript and the bundler, and tailwind.css must point to the stylesheet your app loads. Do not reinitialize an already configured project.

   Only if components.json is missing; run inside the existing app and follow its framework setup.

   npx shadcn@latest init

   Copy first-time setup command
3. 3.

   Include the installed sources in Tailwind

   Keep the host's standard shadcn theme variables, Tailwind @theme mappings, and base border styles loaded (background, foreground, border, sidebar, and chart tokens). Ensure Tailwind scans the actual installed components directory. Restricted source(none), ignored paths, and monorepos may need an @source path relative to the stylesheet. For theme='dark', use a class-based dark variant in the host CSS.

4. 4.

   Import through your configured components alias

   The @components/ entry is a registry target placeholder, not a JavaScript import. Replace the example's @/components prefix with components.json aliases.components, verify the file printed by the CLI, and mount it in an existing host route.

/* Example: src/styles.css */
/* Add only if this directory is outside your existing scan scope. */
@source "./components/uiblocks";

/* Required for the recipe theme="dark" class switch. */
@custom-variant dark (&:where(.dark, .dark *));

Setup references: shadcn configuration · Tailwind source scanning · Dark mode

mode, metrics, chartData, customers

Default controlled mode contains no sample metrics, chart points, or customers. Supply real data; explicit mode='demo' opts in to labeled illustrative records. An explicit empty array stays empty in either mode. chartData points use date, revenue, charges, and optional priorRevenue/priorCharges; no hourly data or prior values are invented for host data.

customerQuery, onCustomerQueryChange, pagination, totalCustomers, customerFilterOptions

Query is {search, filters:{Plan:string[], Status:string[]}, page, pageSize}. Client mode filters and paginates supplied rows locally. Server mode renders supplied current-page rows unchanged and uses totalCustomers for pagination; the host must update rows, total, and query from its service. Search/filter changes reset page to 1. Supply customerFilterOptions={Plan:string[], Status:string[]} for service-wide values across all remote pages; supplied values, current-row values, and selected values remain available. Controlled fallback uses only actual rows and selected values, never demo choices. Never pass the full dataset as a remote page or filter it twice.

period, dateRange, onPeriodChange, onDateRangeChange

Control day/week/month/year and {from,to} ISO date strings. Callbacks let the host fetch actual aggregations; chartData is already aggregated and is not synthesized or filtered again. Controls are disabled in controlled mode without their callback. Dates start blank until the host supplies a range.

loading, error, onRetry, onExport, onCustomerAction

Provide real loading and error state. Retry/refresh delegates to onRetry; export receives the complete CustomerQuery; customer actions receive 'view' or 'contact' and the unchanged row. Handlers can return promises; rejected actions display their actual error and never report success. Business actions without a host handler are disabled in controlled mode. No automatic polling, export, mail, or network request is performed.

brand, title, description, navigation, headerSlot, theme, className

Set real identity, copy, ordinary host navigation URLs, and account controls. The sidebar and layout retain the dashboard block's neutral surfaces, blue chart accent, spacing, and responsive customer table. Inherit the host theme or use a class-based dark variant.