gui/CONTRIBUTING.md

Contributing to hanzogui

To set up your development environment you'll need bun installed, then clone and install:

git clone https://github.com/hanzoai/gui
cd hanzogui
bun install

The first install will automatically build all packages.

If you are developing actively you can run this to watch and rebuild js and types as you edit:

bun run watch

We compile out js to dist for "0-setup" installs by compiling a .native version of every file, and then in every web file we replace react-native with react-native-web. We also build our types out to ./types/*.d.ts for a variety of reasons - it means we can't cause type issues for people with stricter configurations using our packages, it means we can track type regressions (the styled() type setup is impossible delicate to explosions of complexity), and it's generally faster for end users.

Linking hanzogui into your existing project

Most package managers have a link command that lets you link in the local hanzogui to your project, we've built a package we found useful that works with bun or yarn depending on your configuration:

npm i -g lllink
lllink ~/path/to/hanzogui

Running native apps

There's a few ways to run code in the repo, generally for native, there's two ways:

bun run sandbox

Is a bit easier but runs on One (the One framework, one dev).

If you are ok to build the native apps, then:

bun run kitchen-sink

That requires building the native apps:

# Android
bun run kitchen-sink:build:android

# iOS
bun run kitchen-sink:build:ios

Running web

You can run bun run sandbox or bun run dev (the hanzogui website).

Local Testing Setup

Playwright (web integration tests)

Install browser binaries before first run:

cd apps/kitchen-sink
bun run test:web:setup   # installs chromium
bun run start:web        # start dev server (background)
bun run test:web         # run all web tests

Detox (iOS E2E tests)

Install dependencies:

npm install -g detox-cli
brew tap wix/brew && brew install applesimutils

The run-detox.sh script will automatically:

• Run expo prebuild if the ios/ directory doesn't exist
• Build the Detox framework cache if missing (needed after Xcode updates)
• Start Metro if not already running
• Build the app if the binary is missing or outdated

cd apps/kitchen-sink
bun run detox:run:ios                              # run all iOS tests
bun run detox:run:ios "Sheet"                      # filter by test name
DETOX_DEVICE="iPhone 16 Pro" bun run detox:run:ios # override simulator device

If the Detox framework cache gets corrupted after an Xcode update:

npx detox clean-framework-cache && npx detox build-framework-cache

Fixing libraries

All compiler and CSS generation tests live in pkgs/compiler/static-tests.

There are many native tests in apps/kitchen-sink/tests.

A variety of core tests live in pkgs/core/core-test.

Before submitting a PR, please check everything works across every combination of environments.

Linting & Formatting

The project uses oxfmt + oxlint (Rust-based, fast):

# check formatting + lint
bun run lint

# auto-fix
bun run lint:fix

# format only
bun run format

Other ways to Contribute

Join the Discord.