# How to Contribute to Superset Development: Complete Guide to the Bun + Turbo Monorepo

> Learn how to contribute to Apache Superset development. Our guide walks you through forking, setting up the monorepo with Bun, testing, and submitting your first pull request.

- Repository: [Superset/superset](https://github.com/superset-sh/superset)
- Tags: how-to-guide
- Published: 2026-03-08

---

**To contribute to Superset, fork the repository, run `bun install` to set up the monorepo, create a feature branch, and submit a pull request after verifying your changes pass `bun test` and the Biome linting checks enforced in [`.github/workflows/ci.yml`](https://github.com/superset-sh/superset/blob/main/.github/workflows/ci.yml).**

Superset (superset-sh/superset) is a terminal-based workspace for coding agents organized as a **Bun + Turbo monorepo**. The project splits functionality between runnable applications in `apps/` and shared libraries in `packages/`, requiring specific tooling knowledge to contribute effectively. This guide walks through the complete contribution workflow—from environment setup to passing CI checks—based on the actual source code structure and conventions defined in [`CONTRIBUTING.md`](https://github.com/superset-sh/superset/blob/main/CONTRIBUTING.md) and [`AGENTS.md`](https://github.com/superset-sh/superset/blob/main/AGENTS.md).

## Repository Architecture

Understanding the monorepo layout is essential before contributing. The project uses **Turborepo** to manage dependencies and build pipelines across distinct areas:

- **`apps/`** – Contains runnable front-end applications including the web UI, desktop Electron app, and marketing site.
- **`packages/`** – Houses shared libraries such as UI components (`packages/ui`), database schema (`packages/db`), authentication logic, and agent core functionality.
- **`tooling/typescript/`** – Provides shared TypeScript configuration used across the entire monorepo.
- **`.github/workflows/`** – Contains CI/CD definitions, primarily [`ci.yml`](https://github.com/superset-sh/superset/blob/main/ci.yml) which validates all pull requests.

The root configuration files `turbo.jsonc` and [`package.json`](https://github.com/superset-sh/superset/blob/main/package.json) define the workspace boundaries and available scripts. For detailed conventions regarding package structure and agent-specific rules, consult [`AGENTS.md`](https://github.com/superset-sh/superset/blob/main/AGENTS.md) in the repository root.

## Initial Environment Setup

Before writing code, configure your local environment to match the project's Bun-based toolchain.

1. **Fork and clone** the repository:
   ```bash
   git clone https://github.com/your-username/superset.git
   cd superset
   ```

2. **Configure environment variables**:
   ```bash
   cp .env.example .env
   # For local development without full validation:

   echo 'SKIP_ENV_VALIDATION=1' >> .env
   ```

3. **Install dependencies** using Bun (required):
   ```bash
   bun install
   ```

This installs all workspace dependencies and configures the monorepo interlinks defined in the root [`package.json`](https://github.com/superset-sh/superset/blob/main/package.json).

## Development Workflow

Follow the standard fork-branch-PR workflow while respecting the specific commands required by this codebase.

### Creating a Branch

Create a descriptive feature branch:

```bash
git checkout -b feature/your-awesome-change

```

### Running the Application

Start the development servers for the specific app you are modifying:

- **Web UI and API**: Run `bun dev` from the root to start all development servers simultaneously (web, API, desktop, and others as configured in `turbo.jsonc`).
- **Desktop (Electron)**: Build the application with `bun run build`, then open `apps/desktop/release` to test the packaged binary.

### Code Quality Checks

Superset enforces strict style rules using **Biome**. Run these commands before committing:

```bash
bun run lint:fix    # Auto-fix linting issues

bun run format      # Format code with Biome

bun run typecheck   # Verify TypeScript across the monorepo

```

These checks mirror the validation performed by [`.github/workflows/ci.yml`](https://github.com/superset-sh/superset/blob/main/.github/workflows/ci.yml).

### Testing

Write or update tests co-located with your source files (e.g., [`Component.test.tsx`](https://github.com/superset-sh/superset/blob/main/Component.test.tsx) alongside [`Component.tsx`](https://github.com/superset-sh/superset/blob/main/Component.tsx)). Execute the test suite:

```bash
bun test

```

Ensure new logic is covered and existing tests remain green.

### Submitting Changes

1. Commit using descriptive messages:
   ```bash
   git add .
   git commit -m "feat: brief description of change"
   git push origin feature/your-awesome-change
   ```

2. Open a Pull Request following the template in [`CONTRIBUTING.md`](https://github.com/superset-sh/superset/blob/main/CONTRIBUTING.md), link related issues, and enable "Allow edits from maintainers".

3. **CI validation**: GitHub Actions automatically runs linting, formatting, type-checking, and tests. All checks must pass before merge.

## Code Quality Standards

The project maintains high code quality through automated tooling and architectural guidelines.

**Biome Configuration**: Unlike projects with per-package linting rules, Superset runs Biome exclusively from the root directory. Do not add separate Biome configurations in subpackages.

**Clean Code Principles**: Contributions must follow Clean Code guidelines as outlined in [`CONTRIBUTING.md`](https://github.com/superset-sh/superset/blob/main/CONTRIBUTING.md). This includes meaningful variable names, single-responsibility functions, and avoiding unnecessary complexity.

**Type Safety**: Avoid `any` types unless absolutely necessary. The shared TypeScript configuration in `tooling/typescript/` enforces strict mode across the monorepo.

**API Contracts**: When modifying backend functionality, update shared tRPC definitions in `packages/trpc` to keep type safety synchronized between client and server.

## Extending Core Systems

### Adding UI Components

The project uses **shadcn/ui** for component management. To add a new component:

```bash
cd packages/ui
npx shadcn@latest add button

```

This generates files at [`packages/ui/src/components/ui/button.tsx`](https://github.com/superset-sh/superset/blob/main/packages/ui/src/components/ui/button.tsx). Import and use these components across apps in the `apps/` directory.

### Database Schema Changes

Extend the **Drizzle ORM** schema in `packages/db/src/schema/`:

```typescript
// packages/db/src/schema/my_table.ts
import { pgTable, serial, text } from 'drizzle-orm/pg-core';

export const myTable = pgTable('my_table', {
  id: serial('id').primaryKey(),
  name: text('name').notNull(),
});

```

After modifying schema files, generate migrations using `drizzle-kit` (typically performed by maintainers):

```bash
bunx drizzle-kit generate --name add_my_table

```

### Adding tRPC Procedures

Define new API endpoints in `packages/trpc/src/router/`:

```typescript
// packages/trpc/src/router/example.ts
import { router, publicProcedure } from '../trpc';

export const exampleRouter = router({
  hello: publicProcedure.input(z.string()).query(({ input }) => `Hello ${input}`),
});

```

Export the router in [`packages/trpc/src/router/index.ts`](https://github.com/superset-sh/superset/blob/main/packages/trpc/src/router/index.ts) for automatic server discovery.

## CI/CD Pipeline

The [`.github/workflows/ci.yml`](https://github.com/superset-sh/superset/blob/main/.github/workflows/ci.yml) file defines the validation pipeline that runs on every push and pull request. This workflow executes:

1. **Lint and Format**: Validates Biome rules across the monorepo.
2. **Type Checking**: Runs `bun run typecheck` to ensure TypeScript integrity.
3. **Test Execution**: Runs `bun test` to verify logic correctness.

Additional workflows handle desktop releases ([`release-desktop.yml`](https://github.com/superset-sh/superset/blob/main/release-desktop.yml)) and preview deployments ([`deploy-preview.yml`](https://github.com/superset-sh/superset/blob/main/deploy-preview.yml)), though contributors typically only need to ensure the main CI workflow passes.

## Summary

- **Superset** is a Bun + Turbo monorepo with apps in `apps/` and shared packages in `packages/`.
- **Setup**: Fork, clone, copy `.env.example`, and run `bun install`.
- **Development**: Use `bun dev` for local servers and `bun test` for validation.
- **Quality**: Run `bun run lint:fix` and `bun run format` before submitting; Biome config is root-only.
- **Architecture**: Extend UI via `packages/ui`, database via `packages/db`, and APIs via `packages/trpc`.
- **Submission**: Ensure all CI checks in [`.github/workflows/ci.yml`](https://github.com/superset-sh/superset/blob/main/.github/workflows/ci.yml) pass before requesting review.

## Frequently Asked Questions

### What package manager does Superset use?

The project uses **Bun** exclusively. Do not use npm, yarn, or pnpm. All scripts in [`package.json`](https://github.com/superset-sh/superset/blob/main/package.json) (such as `bun dev`, `bun test`, and `bun run lint:fix`) assume Bun is installed.

### Where should I add new React components?

Add reusable UI components to `packages/ui` using the shadcn/ui CLI. App-specific components belong in the respective `apps/` directory (e.g., `apps/web/src/components`). Always check [`packages/ui/README.md`](https://github.com/superset-sh/superset/blob/main/packages/ui/README.md) for the component creation workflow.

### How do I skip environment validation during local development?

Append `SKIP_ENV_VALIDATION=1` to your `.env` file. This allows the application to start without requiring production API keys or database URLs, though some features may be limited.

### What should I do if CI fails on my pull request?

Run the exact checks locally that CI runs: `bun run lint:fix`, `bun run format`, `bun run typecheck`, and `bun test`. Fix any reported errors, amend your commit, and force-push to your branch. The PR will automatically re-trigger the workflow defined in [`.github/workflows/ci.yml`](https://github.com/superset-sh/superset/blob/main/.github/workflows/ci.yml).