shadcn/ui Integration
Relevant source files
The following files were used as context for generating this wiki page:
Better Tables adopts a "shadcn-style" distribution model for its UI components. Instead of installing @better-tables/ui as a traditional NPM dependency, the project provides a Command Line Interface (CLI) that copies the source code of the components directly into the consumer's codebase. This approach ensures that developers have full ownership and customization capabilities over the table UI, filters, and hooks.
The integration relies on an existing shadcn/ui setup within the target project. The CLI detects the project's configuration (via components.json), validates that required base shadcn components are present, and installs any missing dependencies before placing the Better Tables components into the designated directories.
Sources: README.md:70-76, CLAUDE.md:12-14, packages/cli/src/commands/init.ts:36-41
Integration Architecture
The integration logic is primarily housed within the @better-tables/cli package. The init command serves as the entry point for the integration process, orchestrating environment detection, dependency validation, and file transformation.
Initialization Flow
When a user executes bunx @better-tables/cli init, the system performs a multi-step validation and setup routine:
- Project Detection: Verifies if the project is a Next.js environment and identifies the active package manager (Bun, NPM, or PNPM).
- shadcn/ui Validation: Checks for the existence of
components.jsonto ensure shadcn/ui is initialized. - Dependency Check: Verifies that required packages like
zustandand@dnd-kitare installed. - Component Audit: Identifies which standard shadcn/ui components (e.g., Button, Input, Popover) are missing from the project but required by Better Tables.
- Source Copying: Copies the internal
@better-tables/uisource files to the local project, applying import transformations to match the user's defined aliases.
Sources: packages/cli/src/commands/init.ts:89-220, packages/cli/src/lib/shadcn.ts:13-25
Implementation Logic
The following diagram illustrates the sequence of operations during the shadcn integration process:
The CLI uses the project's own configuration to determine where to place the new files, ensuring compatibility with custom folder structures.
Sources: packages/cli/src/commands/init.ts:153-240, packages/cli/src/lib/shadcn.ts:80-105
Required shadcn/ui Primitives
Better Tables UI components are built upon several standard shadcn/ui primitives. The CLI ensures these are present to prevent runtime errors after the source is copied.
| Component | Purpose in Better Tables |
|---|---|
| Button | Table actions, pagination controls, and filter triggers. |
| Input | Text-based filtering and search functionality. |
| Popover | Housing complex filter menus and date pickers. |
| Command | Used for searchable option lists in filters. |
| Checkbox | Row selection and boolean filtering. |
| Badge | Displaying active filter states and status columns. |
| Calendar | Date range and specific date filtering. |
| Separator | Visual division in menus and table headers. |
Sources: packages/cli/src/lib/shadcn.ts:8-11, packages/cli/src/commands/init.ts:168-180
Configuration and Aliases
The integration respects the aliases defined in the consumer's components.json. During the copy process, the CLI transforms import statements within the Better Tables source code to point to the correct local paths for shadcn primitives and utility functions.
Alias Resolution Logic
The CLI extracts alias prefixes to provide helpful post-installation instructions. For instance, if a user has configured @/components as their component alias, the CLI will suggest imports using that specific prefix.
// Example transformation logic reference
const configResult = getConfig(cwd);
const { config, resolvedPaths, isTypeScript } = configResult;
const aliasPrefix = getAliasPrefix(config);
console.log(pc.cyan(`import { BetterTable } from '${aliasPrefix}components/${componentsPath}/table/table';`));
Sources: packages/cli/src/commands/init.ts:153-162, packages/cli/src/commands/init.ts:251-255
Module Installation
Developers can choose to install specific subsets of the UI code. While the core UI module is always required, other features are optional.
The logic ensures that core is always the first module processed, followed by any additional modules specified via the --modules flag.
Sources: packages/cli/src/lib/module-install.ts:26-37, packages/cli/src/commands/init.ts:80-86
Conclusion
The shadcn/ui integration for Better Tables is a developer-centric distribution method that prioritizes flexibility and ownership. By leveraging the project's existing shadcn configuration, the CLI automates the complex task of wiring up a sophisticated data table while maintaining the "copy-paste" philosophy of modern React UI development.
Sources: plans/009-dx-hygiene-sweep.md:154-165, README.md:70-75