Contribution Guide
Relevant source files
The following files were used as context for generating this wiki page:
This guide provides the necessary technical and procedural framework for contributing to the Better Tables project. It outlines the development environment setup, coding conventions, testing protocols, and the release process mandated by the project's architectural standards.
Contributors must adhere to the core philosophy of maintaining end-to-end type safety and high DX (Developer Experience) across all packages, including core, ui, cli, and various database adapters.
Sources: CONTRIBUTING.md:1-6, CLAUDE.md:1-5, README.md:1-10
Development Environment Setup
Better Tables uses a monorepo structure managed with Bun. The project requires Bun (version pinned in package.json) and Node.js 18+.
Initial Setup Commands
git clone https://github.com/Better-Tables/better-tables.git
cd better-tables
bun install
bun run build # Build all packages
bun run typecheck # Verify type safety across the monorepo
Sources: CONTRIBUTING.md:8-16, CLAUDE.md:32-35
Package Architecture
The project is divided into several specialized packages:
| Package | Path | Type | Responsibility |
|---|---|---|---|
@better-tables/core | packages/core | Published | Column builders, filter/sort/pagination managers. |
@better-tables/ui | packages/ui | Private | React components (distributed via CLI copy). |
@better-tables/cli | packages/cli | Published | better-tables init command and UI distribution. |
@better-tables/adapters-drizzle | packages/adapters/drizzle | Published | Drizzle ORM integration and SQL generation. |
@better-tables/adapters-toolkit | packages/adapters/toolkit | Published | Shared primitives for building new adapters. |
Sources: CLAUDE.md:7-17, README.md:214-230
Development Workflow
Branching and Commits
- Branch Names: Short, kebab-case (e.g.,
fix-join-count-inflation). No prefix is required. - Commit Messages: Use imperative-mood, present-tense sentences (e.g., "Add sideEffects false to core").
- Structure: Prefer one logical change per commit. If following a plan from
plans/, align commits with the plan's defined steps.
Sources: CONTRIBUTING.md:23-31
Type Safety and Linting
Type safety is the project's "crown jewel." All contributions must pass a root-level typecheck.
- Linting: Use
biome.- To check:
cd packages/<pkg> && bun run lint. - Caution: The root
bun run lintscript mutates files (--write --unsafe). Do not use it for simple verification.
- To check:
- Strictness: The project enforces
noUncheckedIndexedAccessandexactOptionalPropertyTypes.
Sources: CLAUDE.md:40-42, CONTRIBUTING.md:52-54, plans/README.md:144-147
Mermaid: Contribution Flow
The following diagram illustrates the lifecycle of a contribution from local development to the changeset requirement.
Sources: CONTRIBUTING.md:33-58, CLAUDE.md:31-43
Testing Protocols
Contributors are responsible for ensuring that all package-level tests pass before submission.
- Global Tests:
bun run test(from root). - Scoped Tests:
cd packages/<name> && bun test. - Integration Tests: Drizzle integration tests require a local SQLite environment. MySQL and Postgres tests are skipped unless credentials are provided via
.env.local.
Sources: CLAUDE.md:36-39, CLAUDE.md:46-51
Release and Changeset Process
Better Tables uses Changesets to manage versioning for published packages.
Creating a Changeset
Any user-facing change to a published package (core, cli, adapters-drizzle, adapters-toolkit) requires a changeset file.
bun run changeset
Contributors must select the appropriate bump type:
- Patch: Bug fixes and internal improvements.
- Minor: New features or breaking changes in the
0.xwindow (per Release Policy). - Major: Significant breaking changes (typically reserved for
1.0+).
Sources: CONTRIBUTING.md:33-43, plans/README.md:10-15
Release Policy
The project follows a specific policy for version 0.6.0 and beyond:
- No Deprecation Cycles: Breaking changes replace old surfaces outright to avoid maintenance debt.
- Migration Guides: Every breaking change must be documented in
MIGRATION.md. - URL Compatibility: The system must maintain read-compatibility for legacy
c:URL filter payloads.
Sources: plans/README.md:10-16, plans/019-migration-guide.md:12-16
UI Distribution (CLI)
The @better-tables/ui package is not published to npm. It is distributed via the CLI using a "shadcn-style" copy mechanism.
init Command Architecture
The CLI init command copies source files from the ui package into the consumer's project.
- Source:
packages/cli/ui-src/. - Target: Defined by the consumer's
components.jsonor CLI flags. - Transformation: The CLI rewrites import aliases during the copy process to match the consumer's configuration.
Sources: README.md:95-103, plans/039-documentation-truth.md:108-115
Code of Conduct
All contributors are expected to uphold the project's standards of professional behavior.
Standards of Behavior
- Positive: Being respectful, accepting constructive criticism, and focusing on community benefit.
- Unacceptable: Sexualized language, trolling, personal attacks, and public/private harassment.
Enforcement
Community leaders have the authority to remove or reject contributions that violate these standards. Consequences range from private warnings to permanent bans.
Sources: CODE_OF_CONDUCT.md:10-53
Conclusion
Contributing to Better Tables requires a commitment to the project's strict type-safety standards and its unique CLI-based UI distribution model. By following the protocols for changesets, local testing, and the 0.6 Release Policy, contributors help maintain the library's goal of being the most developer-friendly table solution for React.
Sources: README.md:7-12, plans/README.md:10-16