Skip to content

Latest commit

 

History

History
189 lines (144 loc) · 7.46 KB

CLAUDE.md

File metadata and controls

189 lines (144 loc) · 7.46 KB

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Repository Overview

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)

Development Commands

Note: This project uses Yarn as the package manager.

Core Build Commands

# 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

Testing Commands

# 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 Development

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 .mdx under topic directories (e.g. admin/ai/, docs/explore-analyze/).
  • Frontmatter uses title and description keys.
  • Navigation is registered in docs-mintlify/docs.json (pages must be added to the relevant group to 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.md for full conventions.

Architecture Overview

Monorepo Structure

  • /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
  • /rust: Rust components including CubeSQL (SQL interface) and CubeStore (distributed storage)
  • /docs-mintlify: Mintlify documentation site
  • /examples: Example implementations and recipes

Key Components

  1. Schema Compiler: Compiles data models into executable queries
  2. Query Orchestrator: Manages query execution, caching, and pre-aggregations
  3. API Gateway: Provides REST, GraphQL, and SQL APIs
  4. CubeSQL: Postgres-compatible SQL interface (Rust)
  5. CubeStore: Distributed OLAP storage engine (Rust)
  6. Tesseract: Native SQL planner (Rust) located in /rust/cube/cubesqlplanner - the default planner; set CUBEJS_TESSERACT_SQL_PLANNER=false to fall back to the deprecated legacy planner. Tesseract pre-aggregation planning follows this flag and cannot be toggled independently

Package Management

  • Uses Yarn workspaces with Lerna for package management
  • TypeScript compilation is coordinated across packages
  • Jest for unit testing with package-specific configurations

Testing Approach

Unit Tests

  • Most packages have Jest-based unit tests in /test directories
  • TypeScript packages use jest.config.js with TypeScript compilation
  • Snapshot testing for SQL compilation and query planning
  • To call a protected method from a test, subclass the class in the test file and widen the method to public (class TestFoo extends Foo { public bar() { return super.bar(); } }) instead of casting the instance to any. Casts hide signature changes from the compiler; the subclass keeps the call type-checked. private members cannot be widened this way.

Integration Tests

  • Driver-specific integration tests in /packages/cubejs-testing-drivers
  • End-to-end tests in /packages/cubejs-testing
  • Docker-based testing environments for database drivers

Test Commands

# 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

Development Workflow

  1. Making Changes: Work in individual packages, changes are coordinated via Lerna
  2. Building: Use yarn tsc to compile TypeScript across all packages
  3. Testing: Run relevant tests for modified packages
  4. Linting: Ensure code passes yarn lint before committing

TypeScript

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.

Rust

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.

Git

Use conventional commits with these prefixes:

  • feat: — new user-facing features
  • fix: — bug fixes users can observe
  • docs: — documentation changes
  • refactor: — refactoring of shipped code (refactors of tests, CI or tooling are chore:)
  • perf: — performance improvements
  • chore: — 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.

Common File Patterns

  • *.test.ts/js: Jest unit tests
  • jest.config.js: Jest configuration per package
  • tsconfig.json: TypeScript configuration (inherits from root)
  • CHANGELOG.md: Per-package changelogs maintained by Lerna
  • src/: Source code directory
  • dist/: Compiled output (not committed)

Important Notes

  • Documentation lives in /docs-mintlify (Mintlify). See docs-mintlify/CLAUDE.md.
  • The main Cube application development happens in /packages
  • For data model changes, focus on cubejs-schema-compiler package
  • For query execution changes, focus on cubejs-query-orchestrator package
  • Database connectivity is handled by individual driver packages

Key Dependencies

  • 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