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

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.

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 and 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 which validates all pull requests.

The root configuration files turbo.jsonc and package.json define the workspace boundaries and available scripts. For detailed conventions regarding package structure and agent-specific rules, consult 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:

   git clone https://github.com/your-username/superset.git
   cd superset

2. Configure environment variables:

   cp .env.example .env
   # For local development without full validation:
   
   echo 'SKIP_ENV_VALIDATION=1' >> .env

3. Install dependencies using Bun (required):

   bun install

This installs all workspace dependencies and configures the monorepo interlinks defined in the root 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:

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:

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.

Testing

Write or update tests co-located with your source files (e.g., Component.test.tsx alongside Component.tsx). Execute the test suite:

bun test

Ensure new logic is covered and existing tests remain green.

Submitting Changes

1. Commit using descriptive messages:

   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, 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. 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:

cd packages/ui
npx shadcn@latest add button

This generates files at 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/:

// 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):

bunx drizzle-kit generate --name add_my_table

Adding tRPC Procedures

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

// 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 for automatic server discovery.

CI/CD Pipeline

The .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) and preview deployments (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 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 (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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}