CLI Generator Tool
Relevant source files
The following files were used as context for generating this wiki page:
The CLI Generator Tool, packaged as @better-tables/cli, is a central developer experience (DX) utility designed to streamline the initialization and expansion of the Better Tables ecosystem within consumer projects. Its primary purpose is to automate the setup of the private @better-tables/ui components, which are distributed via source-code copying rather than traditional npm package installation.
The tool manages project initialization, dependency validation, and the incremental addition of UI modules. It ensures that the copied source code is compatible with the user's project structure by transforming imports to match local alias configurations (e.g., shadcn/ui paths). By bundling the UI source code directly within the CLI package, it provides version-exact, offline-capable distribution of table components, hooks, and stores.
Sources: packages/cli/README.md:1-15, plans/037-cli-bundled-ui-source.md:21-36, CLAUDE.md:11-13
Architecture and Core Components
The CLI Generator Tool is built as a TypeScript application bundled using tsdown. It follows a command-based architecture where logic is encapsulated within specific command modules (e.g., init, add, docs).
Core Commands
| Command | Description | Key Responsibilities |
|---|---|---|
init | Initial project setup. | Validates shadcn, checks dependencies, installs required UI components, and copies core files. |
add | Incremental module addition. | Allows users to opt-in to specific features like "actions" by copying specific file subsets. |
docs | Documentation utility. | Opens relevant documentation (main, core, ui, or drizzle) in the user's default browser. |
Sources: packages/cli/README.md:19-45, plans/059-ui-modules-and-actions-extraction.md:118-128
Distribution Model
Unlike the core logic and adapters, the UI components are marked as "private": true and are not published to npm. The CLI acts as the exclusive distribution vehicle for these components. To prevent version skew and remove network dependencies, the UI source code is bundled into the CLI tarball at build time into a ui-src/ directory.
Sources: CLAUDE.md:46-51, plans/037-cli-bundled-ui-source.md:32-36
Initialization Logic (init)
The init command performs a multi-step sequence to prepare a project for Better Tables. It relies heavily on the presence of a shadcn/ui configuration.
The diagram shows the sequential validation and execution flow of the init command.
Sources: packages/cli/README.md:65-75, plans/009-dx-hygiene-sweep.md:175-180
Dependency and Environment Validation
The tool specifically checks for the following runtime dependencies which must be direct dependencies in the consumer project:
@better-tables/corezustand@dnd-kit/core,@dnd-kit/sortable,@dnd-kit/modifiers,@dnd-kit/utilities
Sources: packages/cli/README.md:92-101
UI Modules and Expansion (add)
The CLI supports an opt-in module tier. This prevents "bloat" in the default installation by allowing users to add specific capabilities only when needed.
Module Manifest Structure
Modules are defined in a manifest that maps specific files to functional groups. As of the current architecture:
- Core Module: Includes base table components, filters, hooks, stores, and utilities.
- Actions Module: Includes
actions-toolbar.tsxandaction-confirmation-dialog.tsx.
Sources: plans/059-ui-modules-and-actions-extraction.md:105-115
Import Transformation
A critical feature of the generator is the transformImports function. This ensures that when files are copied from the CLI's internal ui-src to the user project, the import paths are updated to match the user's alias configuration defined in components.json.
Sources: packages/cli/README.md:86-88, plans/037-cli-bundled-ui-source.md:52-53
Technical Implementation Details
File Operations and Resolution
The tool utilizes a resolver to locate the UI source code. It prioritizes the bundled ui-src directory (standard for npm installs) but falls back to the monorepo workspace path (packages/ui/src) during local development.
The diagram illustrates how the CLI resolves the location of the UI source files regardless of the environment (production vs. development).
Sources: plans/037-cli-bundled-ui-source.md:112-135
Build and Packaging
The CLI package configuration ensures that the generator is always shipped with the necessary source assets.
| Configuration | Value / Script | Purpose |
|---|---|---|
bin | ./dist/cli.mjs | Defines the executable entry point. |
build | tsdown && bun scripts/bundle-ui-src.ts | Compiles logic and syncs UI source files. |
files | ["dist", "ui-src"] | Ensures assets are included in the published tarball. |
Sources: packages/cli/package.json:5-15, plans/037-cli-bundled-ui-source.md:95-103
Summary
The CLI Generator Tool is the primary bridge between the Better Tables library and consumer applications. By automating the installation and configuration of private UI components, it maintains a "shadcn-style" source-distribution model while providing a robust, version-controlled experience. Through its module system and import transformation logic, it allows developers to incrementally build complex table interfaces while ensuring project-specific path compatibility.