Monorepo Architecture
Relevant source files
The following files were used as context for generating this wiki page:
Better Tables is structured as a TypeScript monorepo managed by Turbo and Bun. The architecture follows a modular design pattern that separates core logic, ORM adapters, UI components, and the CLI. This separation ensures that the core logic remains framework-agnostic while providing specialized adapters for different data sources and a CLI for distributing UI components.
The project prioritizes "Better-Auth-style" configuration where a single central instance (betterTables) manages the database adapter and global defaults, while individual tables are defined using a type-safe path-based builder API.
Sources: package.json, CLAUDE.md:8-16, plans/011-table-definition-dx-design.md:36-54
Package Structure
The repository is organized into distinct workspaces under packages/ and apps/. This structure allows for independent versioning of published packages while maintaining private applications like the marketing site within the same repository.
Core and Adapters
@better-tables/core: The engine of the project. It contains column builders, filter/sort/pagination managers, and adapter contract types. It is strictly logic-only, containing no React or database drivers.@better-tables/adapters-drizzle: Implements thecoreadapter contract for Drizzle ORM, handling schema introspection and query generation for Postgres, MySQL, and SQLite.@better-tables/adapters-toolkit: Provides ORM-agnostic primitives (data transforms, schema utilities) to simplify the creation of new adapters.
Distribution and UI
@better-tables/ui: A private package containing React table components, hooks, and stores. It is distributed via the CLI rather than NPM to allow users to customize the shadcn-style components locally.@better-tables/cli: The entry point for developers, providing thebetter-tables initcommand to copy UI components into consumer projects.
Sources: CLAUDE.md:8-16, plans/009-dx-hygiene-sweep.md:214-230
Workspace Layout
| Category | Package Path | NPM Status | Purpose |
|---|---|---|---|
| Core | packages/core | Published | Engine, Types, Managers |
| Adapters | packages/adapters/drizzle | Published | Drizzle ORM implementation |
| Adapters | packages/adapters/toolkit | Published | Shared adapter primitives |
| Tooling | packages/cli | Published | Component distribution CLI |
| Frontend | packages/ui | Private | React Components & Hooks |
| Apps | apps/marketing | Private | Docs, Demos, Marketing site |
Sources: CLAUDE.md:8-16, package.json:5-10
Data Flow Architecture
The data flow follows a unidirectional path from column definitions through an adapter to the UI components. The core package acts as the bridge, defining the contract that adapters must fulfill and that UI components consume.
The diagram shows how column definitions and UI interactions are translated into database queries through the core managers and specific adapters.
Sources: CLAUDE.md:20-25, plans/011-table-definition-dx-design.md:121-137
Build and Developer Experience (DX)
The monorepo utilizes Turbo to orchestrate tasks and Bun for package management and testing.
Tooling Configuration
- Turbo: Tasks like
build,typecheck,test, andlintare defined inturbo.jsonto enable caching and parallel execution. - Bun: The
packageManageris pinned tobun@1.3.11. Bun is used for the workspace catalog, which ensures consistent versions of React (pinned to^19.2.0), Tailwind, and TypeScript across all packages. - Biome: Used for linting and formatting. The root
lintcommand is configured to perform unsafe auto-fixes (biome check --write --unsafe .).
Common Commands
| Command | Description | Context |
|---|---|---|
bun run build | Builds all packages via Turbo | Workspace Root |
bun run typecheck | Runs tsc --noEmit across all packages | Workspace Root |
bun run test | Executes all package test suites | Workspace Root |
bun run changeset | Generates versioning files for published packages | Workspace Root |
better-tables init | CLI command to copy UI into projects | Consumer App |
Sources: package.json:44-54, CLAUDE.md:27-41, CONTRIBUTING.md:10-18, plans/009-dx-hygiene-sweep.md:169-173
Component Distribution Model
Unlike standard libraries, @better-tables/ui is not published to NPM as a dependency. It uses a "copy-flow" model (similar to shadcn/ui). This design choice allows the UI to be a client-boundary chunk where per-file 'use client' directives are preserved for React Server Components (RSC) compatibility.
This diagram illustrates the CLI-based distribution of UI components into a developer's local project.
Sources: plans/009-dx-hygiene-sweep.md:214-230, CLAUDE.md:11-12
Summary
The Better Tables monorepo architecture provides a scalable foundation for a complex data-grid ecosystem. By decoupling the core logic from specific ORMs and UI frameworks, and utilizing a CLI for component distribution, the project achieves high type safety and developer flexibility. The use of Turbo and Bun streamlines the development lifecycle across its multiple interconnected packages.