This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
Cube is a semantic layer for building data applications. This is a monorepo containing the complete Cube ecosystem including:
- Cube backend server and core components
- Client libraries for JavaScript/React/Vue/Angular
- Database drivers for various data sources
- Documentation site
- Rust components (CubeSQL, CubeStore)
Note: This project uses Yarn as the package manager.
# Build all packages
yarn build
# Run TypeScript compilation across all packages
yarn tsc
# Watch mode for TypeScript compilation
yarn tsc:watch
# Clean build artifacts
yarn clean
# Run linting (oxlint over the whole repo) plus the package.json linter
yarn lint
# oxlint only
yarn lint:js
# Fix linting issues
yarn lint:fix
# Lint package.json files
yarn lint:npm# Tests run per package; the root has no test script
cd packages/cubejs-[package-name]
yarn unit # most packages; some also define `test` (unit + integration)Documentation lives in /docs-mintlify. When asked to write or update documentation,
work there unless the user explicitly says otherwise.
cd docs-mintlify
yarn dev # Start the Mintlify dev server- Content is authored as
.mdxunder topic directories (e.g.admin/ai/,docs/explore-analyze/). - Frontmatter uses
titleanddescriptionkeys. - Navigation is registered in
docs-mintlify/docs.json(pages must be added to the relevantgroupto appear in the sidebar). - Use Mintlify components:
<Note>,<Warning>,<Info>,<Tip>,<Steps>/<Step>,<CardGroup>/<Card>. Internal links are root-relative (e.g./admin/ai/rules). - Keep docs concise — most changes are small, surgical edits to existing pages, not new pages or walls of text. Prefer editing an existing page over creating a new one.
- See
docs-mintlify/CLAUDE.mdfor full conventions.
/packages: All JavaScript/TypeScript packages managed by Lerna- Core packages:
cubejs-server-core,cubejs-schema-compiler,cubejs-query-orchestrator - Client libraries:
cubejs-client-core,cubejs-client-react, etc. - Database drivers:
cubejs-postgres-driver,cubejs-bigquery-driver, etc. - API layer:
cubejs-api-gateway
- Core packages:
/rust: Rust components including CubeSQL (SQL interface) and CubeStore (distributed storage)/docs-mintlify: Mintlify documentation site/examples: Example implementations and recipes
- Schema Compiler: Compiles data models into executable queries
- Query Orchestrator: Manages query execution, caching, and pre-aggregations
- API Gateway: Provides REST, GraphQL, and SQL APIs
- CubeSQL: Postgres-compatible SQL interface (Rust)
- CubeStore: Distributed OLAP storage engine (Rust)
- Tesseract: Native SQL planner (Rust) located in
/rust/cube/cubesqlplanner- the default planner; setCUBEJS_TESSERACT_SQL_PLANNER=falseto fall back to the deprecated legacy planner. Tesseract pre-aggregation planning follows this flag and cannot be toggled independently
- Uses Yarn workspaces with Lerna for package management
- TypeScript compilation is coordinated across packages
- Jest for unit testing with package-specific configurations
- Most packages have Jest-based unit tests in
/testdirectories - TypeScript packages use
jest.config.jswith TypeScript compilation - Snapshot testing for SQL compilation and query planning
- To call a
protectedmethod from a test, subclass the class in the test file and widen the method topublic(class TestFoo extends Foo { public bar() { return super.bar(); } }) instead of casting the instance toany. Casts hide signature changes from the compiler; the subclass keeps the call type-checked.privatemembers cannot be widened this way.
- Driver-specific integration tests in
/packages/cubejs-testing-drivers - End-to-end tests in
/packages/cubejs-testing - Docker-based testing environments for database drivers
# Individual package testing
cd packages/[package-name]
yarn unit # most packages; some also define `test` (unit + integration)
# Driver integration tests (requires Docker)
cd packages/cubejs-testing-drivers
yarn tsc && yarn postgres-full # one script per driver/suite, see package.json- Making Changes: Work in individual packages, changes are coordinated via Lerna
- Building: Use
yarn tscto compile TypeScript across all packages - Testing: Run relevant tests for modified packages
- Linting: Ensure code passes
yarn lintbefore committing
Use protected, not private, for class members that shouldn't be public (methods, fields and
constructor parameter properties). private blocks subclasses — including test subclasses that
widen a member to public — and downstream code that extends Cube classes.
Every unsafe block and unsafe impl needs a short // SAFETY: comment saying why it is sound
(not what the code does). Every unsafe fn documents its caller contract in /// # Safety.
Use conventional commits with these prefixes:
feat:— new user-facing featuresfix:— bug fixes users can observedocs:— documentation changesrefactor:— refactoring of shipped code (refactors of tests, CI or tooling arechore:)perf:— performance improvementschore:— internal changes: tests, CI, build/tooling, dependency bumps
feat: and fix: exist to surface a change to users in the changelog. If users can't notice the
change (a test fix, a CI tweak, a refactor of test helpers), use chore: even when it "fixes"
something — e.g. chore(query-orchestrator): Revive QueryOrchestrator.test, not fix(...).
The same rule applies to PR titles, since the squash commit takes the PR title.
Include scope in parentheses when applicable, e.g., fix(tesseract): or feat(databricks-jdbc-driver):.
Start the subject after the prefix with a capital letter: feat(tesseract): Support rolling windows,
not feat(tesseract): support rolling windows. This applies to PR titles too.
PRs are squash-merged. When merging one, use the merge-pr skill: always pass --body (but not
--subject) to gh pr merge, otherwise the raw PR description (template checklist included)
becomes the squash commit body.
*.test.ts/js: Jest unit testsjest.config.js: Jest configuration per packagetsconfig.json: TypeScript configuration (inherits from root)CHANGELOG.md: Per-package changelogs maintained by Lernasrc/: Source code directorydist/: Compiled output (not committed)
- Documentation lives in
/docs-mintlify(Mintlify). Seedocs-mintlify/CLAUDE.md. - The main Cube application development happens in
/packages - For data model changes, focus on
cubejs-schema-compilerpackage - For query execution changes, focus on
cubejs-query-orchestratorpackage - Database connectivity is handled by individual driver packages
- Lerna: Monorepo management and publishing
- TypeScript: Primary language for most packages
- Jest: Testing framework
- Rollup: Bundling for client libraries
- Docker: Testing environments for database drivers