Full contribution guidelines

Contributing

Welcome! We’re glad you’re interested in Drizzle Cube and want to help us make it better.

Drizzle Cube is maintained by Clifton Cunningham and community contributors. All contributions are reviewed and approved by the maintainer.

There are many ways you can contribute to the Drizzle Cube project:

Submitting bug reports
Submitting feature request
Providing feedback
Contribution guidelines

Submitting bug report

To report a bug or issue, please use our issue form “Bug: ”.

Submitting feature request

To request a feature, please use our issue form and start the title with “Feature Request: ”.

Providing feedback

There are several ways you can provide feedback:

You can add new ticket in Discussions.
Mention me on BlueSky - @cliftonc.nl.

Pre-contribution setup

Installing Node via NVM (if needed)

# https://github.com/nvm-sh/nvm#install--update-script
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
nvm install 22
nvm use 22

Installing npm

Node.js comes with npm by default. We use npm for package management.

Installing Docker

# https://docs.docker.com/get-docker/
# Use Docker's guide to install Docker for your OS.

Cloning the repository

git clone https://github.com/cliftonc/drizzle-cube.git
cd drizzle-cube

Repository structure

📂 src/

Core library source code
- 📂 server/ - Server-side semantic layer implementation
- 📂 client/ - React components and hooks for analytics UI
- 📂 adapters/ - Framework adapters (Hono, Express, Fastify, Next.js)
📂 tests/

Comprehensive test suite with multi-database support
📂 dev/

Development environment with example implementation, so you can test your changes with HMR.
📂 docs/

Documentation and implementation plans when using tools like Claude Code (we encourage this).
📂 ../drizzle-cube-*/

Example projects demonstrating different framework integrations are in separate github repositories.
- drizzle-cube-express/ - Express.js example
- drizzle-cube-fastify/ - Fastify example
- drizzle-cube-hono/ - Hono example
- drizzle-cube-nextjs/ - Next.js example
- drizzle-cube-try-site/ - Interactive sandbox
- drizzle-cube-help-site/ - Main documentation site

Building the project

Run the following script from the root folder to build the project:

npm install && npm run build

To setup postgres and seed with sample data:

npm run dev:setup

Then for development

npm run dev

Then to run the tests (default uses Postgres):

npm t

Commit message guidelines

We have specific rules on how commit messages should be structured.

It’s important to make sure your commit messages are clear, concise, and informative to make it easier for others to understand the changes you are making.

All commit messages should follow the pattern below:

<subject>
<BLANK LINE>
<body>

Example:

Add PostgreSQL array support to measures

Enables aggregation functions on PostgreSQL array columns
for more flexible analytics queries

[!WARNING] All commits should be signed before submitting a PR. Please check the documentation on how to sign commits.

Contributing to the core library

Project structure

📂 src/server/

Server-side semantic layer with type-safe query building, SQL generation, and security
📂 src/client/

React components, hooks, and utilities for building analytics dashboards
📂 src/adapters/

Framework-specific adapters that integrate the semantic layer with web frameworks

Running tests

All tests for Drizzle Cube are integration tests that simulate real databases with different queries and responses. Each test file covers different scenarios for different dialects and drivers. Tests create Docker containers with the needed databases and run test cases there. After every test is run, the Docker container is deleted.

If you have added additional logic to the core library, make sure that all tests complete without any failures.

[!NOTE] If you have added data types, query features, or new functionality, you need to create additional test cases using the new API to ensure it works properly.

Setup test databases via docker:

npm run test:setup

Run default postgres tests:

npm test

Run database-specific tests:

# PostgreSQL (default)
npm run test:postgres

# MySQL
npm run test:mysql

# SQLite
npm run test:sqlite

# All databases
npm run test:all

Run tests in watch mode:

npm run test:watch

Teardown test databases:

npm run test:teardown

PR guidelines

PR titles should follow the pattern below:

[<area>]: <subject>

Examples:

[Server] Add MySQL JSON field support
[Client] Improve chart type selection UX
[Adapters] Add Fastify CORS configuration

PRs should contain a detailed description of everything that was changed.
Commit messages should follow the message style guidelines.
PRs should implement:
- Tests for features that were added.
- Tests for bugs that were fixed.
- Type checking with npm run typecheck
- Linting with npm run lint

[!NOTE] To understand how tests should be created and run, please check the Running tests section.

Contributing to examples

Example projects are located in separate github repositories and follow the same contribution guidelines:

drizzle-cube-express - Express.js with React dashboard
drizzle-cube-fastify - Fastify with React dashboard
drizzle-cube-hono - Hono with React dashboard
drizzle-cube-nextjs - Next.js full-stack application

When contributing to examples:

Ensure examples use the latest version of the core library
Update documentation if adding new features to examples
Test examples work with multiple databases where applicable
Keep examples simple and focused on demonstrating specific features

Development Workflow

Fork and clone the repository
Create a branch for your feature/fix

Set up development environment:

npm install
npm run dev:setup  # Sets up dev database

Make your changes with appropriate tests

Run the test suite:

npm run typecheck
npm run lint
npm run test:all

Create a pull request with a clear description

Architecture Guidelines

Drizzle-First Design: This project is built around Drizzle ORM as the core:

All SQL generation must use Drizzle query builder
Never use string concatenation for SQL
All database operations go through Drizzle
Type safety is enforced through Drizzle schema definitions

Security: SQL injection prevention is paramount:

Use parameterized queries only
Leverage Drizzle’s type safety
Include security context in all cube definitions
Test multi-tenant isolation

Getting Help

📖 Check the documentation
🐛 Search existing issues
💬 Start a discussion

Thank you for contributing to Drizzle Cube! 🐲