Relevant source files

The following files were used as context for generating this wiki page: - [README.md](https://github.com/Better-Tables/better-tables/blob/main/README.md) - [packages/core/README.md](https://github.com/Better-Tables/better-tables/blob/main/packages/core/README.md) - [apps/demo/README.md](https://github.com/Better-Tables/better-tables/blob/main/apps/demo/README.md) - [packages/adapters/drizzle/examples/advanced-relationships.ts](https://github.com/Better-Tables/better-tables/blob/main/packages/adapters/drizzle/examples/advanced-relationships.ts) - [packages/cli/README.md](https://github.com/Better-Tables/better-tables/blob/main/packages/cli/README.md) - [packages/core/src/index.ts](https://github.com/Better-Tables/better-tables/blob/main/packages/core/src/index.ts) - [examples/nextjs-setup-example.md](https://github.com/Better-Tables/better-tables/blob/main/examples/nextjs-setup-example.md) - [apps/demo/lib/db/seed.ts](https://github.com/Better-Tables/better-tables/blob/main/apps/demo/lib/db/seed.ts) - [packages/cli/src/lib/file-operations.ts](https://github.com/Better-Tables/better-tables/blob/main/packages/cli/src/lib/file-operations.ts)

# Project Philosophy The core philosophy of Better Tables is to revolutionize the development of complex, relational data tables in React by prioritizing developer experience, type safety, and abstraction. The project's motto, "Stop writing boilerplate. Start shipping features," encapsulates its primary goal: to eliminate the repetitive and error-prone tasks associated with table state management, data fetching, and UI wiring. Better Tables achieves this by providing a declarative, type-safe, and database-agnostic toolkit. It abstracts away the complexities of filtering, sorting, pagination, and relationship-based data fetching, allowing developers to define table behavior once and have it work seamlessly from the database to the UI. The architecture is intentionally modular, separating core logic, UI components, and data adapters to ensure flexibility and maintainability. Sources: [README.md:1-12](), [README.md:23-31]() ## Core Principles ### 1. Simplicity and Declarative API The project is designed to combat the "soul-crushing mix of useState hooks, prop drilling, and scattered utility functions" often required to build tables. The primary tool for this is a fluent, declarative API for defining columns. Sources: [README.md:16-22]() A `ColumnBuilder` allows developers to define a column's properties, data accessors, and features (like filtering and sorting) in a chained, readable format. This approach centralizes column logic and removes the need for manual state handling for each feature. This diagram illustrates the simplified workflow promoted by Better Tables compared to traditional methods. ```mermaid graph TD subgraph Traditional Way A[Define Columns] --> B[Write useState for Filters] B --> C[Write useState for Sorting] C --> D[Write useState for Pagination] D --> E[Manually Write Filter UI] E --> F[Prop Drill State and Handlers] F --> G[Write Data Fetching Logic] end subgraph Better Tables Way H[Define Columns with Fluent API] --> I[Instantiate BetterTable Component] I --> J[Features Enabled via Props] end A --> H ``` Sources: [README.md:16-22](), [packages/core/README.md:27-72]() ### 2. End-to-End Type Safety A foundational principle is providing full type safety from the database schema to the final rendered UI component. This is achieved by leveraging TypeScript generics throughout the system. The `createColumnBuilder()` function is typed with the data model, ensuring that all accessors are type-checked against the model's properties. This safety extends through the data adapters, which return typed data, and into the UI components that consume it. The diagram below shows the flow of type information through the system. ```mermaid flowchart TD A[Database Schema
(e.g., Drizzle Schema)] --> B[Data Adapter
(Typed Fetch)] B --> C[Data Model
(e.g., interface User)] C --> D["createColumnBuilder<User>()"] D --> E["ColumnDefinition<User>[]"] E --> F["BetterTable Component
(Typed Props)"] F --> G[UI Rendering
(Typed Row Data)] ``` Sources: [README.md:28](), [packages/core/README.md:401-412]() ### 3. Modular and Extensible Architecture Better Tables is structured as a monorepo with a clear separation of concerns, allowing developers to use parts of the system independently or together. ```mermaid graph TD subgraph Monorepo Structure A["@better-tables/core"] B["@better-tables/ui"] C["@better-tables/adapters-drizzle"] D["@better-tables/adapters-memory"] E["@better-tables/cli"] F["apps/demo"] end B --> A C --> A D --> A F --> A F --> B F --> C ``` This diagram shows the dependencies between the main packages. Sources: [README.md:196-213](), [package.json:5-12]() The key packages and their roles are summarized below: | Package | Role | Source Files - | `@better-tables/core` | Provides the foundational, framework-agnostic logic: column builders, state managers, and type definitions. | [packages/core/README.md:3-6](), [packages/core/package.json:3]() - | `@better-tables/ui` | A set of production-ready, accessible React components built with `shadcn/ui` and Radix UI. | [README.md:209](), [packages/ui/package.json:4]() - | `@better-tables/adapters/*` | Connects the core logic to a backend (e.g., Drizzle, REST). Handles query generation and data fetching. | [README.md:121-122](), [README.md:210-211]() - | `@better-tables/cli` | Provides command-line utilities for project initialization and accessing documentation. | [packages/cli/README.md:3-5]() - ### 4. Automatic Relationship Handling The "crown jewel" of Better Tables is its ability to abstract away database joins. By defining columns with dot notation (e.g., `profile.location`), developers signal to the data adapter that a relationship needs to be resolved. The Drizzle adapter, for example, introspects the Drizzle ORM schema to automatically detect one-to-one, one-to-many, and many-to-many relationships. It then generates the necessary `JOIN` queries to fetch and filter data across tables without requiring the developer to write any SQL. Sources: [README.md:32-44](), [README.md:100-113](), [README.md:215-226]() This sequence diagram shows how a filter on a related field is processed: ```mermaid sequenceDiagram participant User as "User Interface" participant Table as "BetterTable Component" participant Adapter as "Drizzle Adapter" participant DB as "Database" User->>Table: Applies filter: "profile.location contains 'SF'" Table->>Adapter: fetchData({ filters: [...] }) Adapter->>Adapter: Detect 'profile' relationship on 'users' table Adapter->>Adapter: Build SQL query with LEFT JOIN on 'profiles' Adapter->>DB: SELECT ... FROM users LEFT JOIN profiles ON ... WHERE profiles.location LIKE '%SF%' DB-->>Adapter: Returns filtered rows Adapter-->>Table: { data: [...], total: ... } Table-->>User: Renders updated table data ``` Sources: [README.md:100-113](), [packages/adapters/drizzle/examples/basic-usage.ts:1-325]() ### 5. Centralized and Shareable State The library provides a robust state management system, abstracting the logic for filters, sorting, and pagination. This state can be automatically synchronized with the URL, making table views easily shareable and bookmarkable. - **State Managers**: The `@better-tables/core` package includes `FilterManager`, `SortingManager`, and `PaginationManager` to handle discrete parts of the table's state. A unified `TableStateManager` coordinates them all. - **URL Persistence**: Filters and other state are serialized into a compressed, URL-safe string. This allows the exact state of the table to be captured in the URL's query parameters. The `serializeFiltersToURL` and `deserializeFiltersFromURL` utilities are key to this feature. This philosophy ensures that the table's state is not ephemeral UI state but a reproducible query that can be shared and re-loaded. Sources: [README.md:168-174](), [packages/core/README.md:143-220](), [apps/demo/README.md:35-37]() ## Conclusion The philosophy of Better Tables is to provide a superior developer experience by abstracting complexity without sacrificing power or type safety. By focusing on a declarative API, modular architecture, and intelligent data adapters that automate relationship handling, the project aims to make the creation of sophisticated data tables a simple, fast, and robust process. This allows developers to focus on application features rather than reinventing table management logic. Sources: [README.md:13-31]()