Repository: cube-js/cube

Stars: 19814

CLAUDE.md Copy Chapter

CLAUDE.md

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

Repository Overview Copy Chapter

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 Copy Chapter

Note: This project uses Yarn as the package manager.

Core Build Commands Copy Section

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 across all packages

yarn lint
Fix linting issues

yarn lint:fix
Lint package.json files

yarn lint:npm

Testing Commands Copy Section

Run tests (most packages have individual test commands)

yarn test
Test individual packages

cd packages/cubejs-[package-name]
yarn test

Documentation Development Copy Section

cd docs
yarn dev    # Start development server
yarn build  # Build for production

Architecture Overview Copy Chapter

Monorepo Structure Copy Section

Key Components Copy Section

Package Management Copy Section

Testing Approach Copy Chapter

Unit Tests Copy Section

Integration Tests Copy Section

Test Commands Copy Section

Individual package testing

cd packages/[package-name]
yarn test
Driver integration tests (requires Docker)

cd packages/cubejs-testing-drivers
yarn test

Development Workflow Copy Chapter

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

Git Copy Chapter

Use conventional commits with these prefixes:
- feat: — new features
- fix: — bug fixes
- docs: — documentation changes
- refactor: — code refactoring

Include scope in parentheses when applicable, e.g., fix(tesseract): or feat(databricks-jdbc-driver):.

Common File Patterns Copy Chapter

- *.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 Copy Chapter

- This is documentation for the old Cube docs site structure (the existing /docs/CLAUDE.md refers to the documentation site)
- 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 Copy Chapter

- 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

README.md Copy Chapter

![]()
<p align="center">
<a href="https://cube.dev?ref=github-readme"><img src="https://raw.githubusercontent.com/cube-js/cube/master/docs/content/cube-core-logo.png" alt="Cube Core — Open-Source Semantic Layer" width="300px"></a>
</p>
<br/>

Website • Docs • Examples • Blog • Slack • X


__Cube Core is an open-source semantic layer.__ Cube Core can be used to build embedded analytics in your applications, create your own business intelligence tool or provide context about data to AI agents. Cube Core is headless and comes with multiple APIs for embedded analytics and BI: REST, GraphQL, and SQL.

If you are looking for a fully integrated platform, check out Cube, a modern AI-first business intelligence platform. We use Cube Core to power it.

<img
src="https://lgo0ecceic.ucarecd.net/418db1f9-7597-4e00-8c10-eba19fcac20f/"
style="border: none"
width="100%"
/>

<p align="center">
<i>Learn more about connecting Cube to <a href="https://cube.dev/cube-core/getting-started/create-a-project?ref=github-readme" target="_blank">data sources</a> and <a href="https://cube.dev/docs/integrations?ref=github-readme" target="_blank">analytics & visualization tools</a>.</i>
</p>

Cube Core was designed to work with all SQL data sources, including cloud data warehouses like Snowflake, Databricks, and BigQuery; query engines like Presto and Amazon Athena; and application databases like Postgres. Cube Core has a built-in relational caching engine to provide sub-second latency and high concurrency for API requests.

Why Cube Core? Copy Chapter

Every business intelligence tool relies on a semantic layer as its core engine—a critical component that defines metrics, dimensions, and business logic while abstracting the complexity of underlying data sources. However, most semantic layers are proprietary, tightly coupled to specific BI platforms, and cannot be reused across different applications.

Cube Core is an open-source project that aims to create an open, modern semantic layer that can be used to power any analytics applications and AI agents. By decoupling the semantic layer from specific tools and making it accessible through standard APIs, Cube Core enables organizations to define their metrics once and use them everywhere—from BI tools to embedded analytics to AI agents.

Getting Started 🚀 Copy Chapter

You can get started with Cube locally or self-host it with Docker.

Once Docker is installed, in a new folder for your project, run the following command:

docker run -p 4000:4000 \
  -p 15432:15432 \
  -v ${PWD}:/cube/conf \
  -e CUBEJS_DEV_MODE=true \
  cubejs/cube

Then, open http://localhost:4000 in your browser to continue setup.

For a step-by-step guide, see the docs.

Cube — Complete Modern BI Tool from Cube Core Creators Copy Section

Cube is a complete modern agentic analytics platform built on Cube Core. It provides a fully integrated solution with a user-friendly interface, advanced analytics capabilities, and managed infrastructure.

<a href="https://cubecloud.dev/auth/signup?ref=github-readme"><img src="https://cubedev-blog-images.s3.us-east-2.amazonaws.com/f1f1eac0-0b44-4c47-936e-33b5c06eedf0.png" alt="Get started now" width="200px"></a>

Resources Copy Chapter

- Documentation
- Getting Started
- Examples & Tutorials
- Architecture

Contributing Copy Chapter

There are many ways you can contribute to Cube Core! Here are a few possibilities:

* Star this repo and follow us on X.
* Add Cube to your stack on Stackshare.
* Upvote issues with 👍 reaction so we know what the demand is for particular issues to prioritize them within the roadmap.
* Create issues every time you feel something is missing or goes wrong.
* Ask questions on Stack Overflow with cube.js tag if others might have these questions as well.
* Provide pull requests for all open issues and especially for those with help wanted and good first issue labels.

All sorts of contributions are welcome and extremely helpful 🙌 Please refer to the contribution guide for more information.

License Copy Chapter

Cube Client is MIT licensed.

Cube Backend is Apache 2.0 licensed.