Contributor Quickstart

Use this guide when you want the shortest path from clone to a validated change.

1. Set Up

You need Bun and Rust 1.99.0 or newer from rustup (curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh). The hub launches Local as the cargo-built mangostudio-runtime binary, and rust-toolchain.toml pins the version rustup installs on first build.

git clone <repo-url>
cd mangostudio
bun install

Optional local config:

mkdir -p ~/.mango
cp .mango/config.toml.example ~/.mango/config.toml
cp .mango/.env.example ~/.mango/.env

2. Run The App

bun run dev

It runs cargo build -p mangostudio-runtime --locked first, so Local has a binary to launch; set MANGOSTUDIO_RUNTIME_BINARY to use one you already built instead. API tests that reach Local need the same binary.

One server, one URL — the API builds and serves the frontend:

App and API: http://localhost:3001

Nothing watches the frontend. After editing a frontend file, rebuild it and refresh the browser — there is no HMR, so a refresh is needed either way:

bun run --filter @mangostudio/frontend build

3. Know Where To Start

Read ../../AGENTS.md for repository rules and routing.
Use ../reference/agent-playbooks.md when you need a feature-by-feature file map.
Use ../reference/testing.md before adding or changing behavior.
Use ../architecture/overview.md for the workspace and module layout.

4. Git Hooks

A lefthook pre-commit hook is installed automatically during bun install. It runs these checks on every commit:

Check	Trigger	Files targeted	Fails commit on
Biome format/lint	`pre-commit`	`*.{ts,tsx,js,jsx,json}`	Format or lint errors
dprint format	`pre-commit`	`*.{md,mdx,toml,yml,yaml}`	Format errors
dprint Dockerfile	`pre-commit`	`{Dockerfile,Dockerfile.*}`	Format errors
Affected checks	`pre-commit`	All staged files	Workspace validation and relevant repository-wide code-health errors

Formatted files are re-staged automatically. The affected-check step is skipped during merge or rebase.

5. Common Commands

bun run check
bun run test
bun run verify   # full local CI gate: check → test --coverage → build --all
bun run build

Targeted lanes:

bun run test --unit
bun run test --integration
bun run test:e2e:setup  # install Chromium before the first e2e run
bun run test --e2e
bun run check --staged    # only workspaces touched by staged files
bun run fix --staged      # auto-fix only affected workspaces

6. Daily Workflow

Start from the nearest route, component, hook, service, or contract.
Trace one layer outward instead of reading the whole repo.
Keep changes scoped to one concern.
Run bun run check after each change set.
Before handoff or PR, run bun run verify (or bun run check && bun run test for a lighter pass).

7. PR Automation

Pull requests are classified by .github/labeler.yml, and the auto-assign.yml workflow assigns you as the owner and requests reviews from contributors who have previously committed to the files your PR changes. Both run automatically — there is no per-label routing config to update when adding labels or onboarding contributors. See ../reference/labels.md for the label taxonomy and when to add one by hand.

../../.github/CONTRIBUTING.md for contribution policy and commit rules
../reference/api.md for endpoint mapping
../operations/deployment.md for standalone builds