Thanks for your interest in improving HostIt! This guide covers how to set up, make a change, and open a pull request. For project background and architecture, read the README; for a deeper engineering map, see CLAUDE.md.
- Use bun — never npm or pnpm, in every directory.
- This is a two-tree repo: the Move package lives at the root (
suicommands), the Next.js dApp inweb/(buncommands). - Never commit secrets.
web/.env.localis git-ignored; only the all-blank.env.local.exampletemplate is tracked. - HostIt is permissionless — no issuer/buyer role split. UI must not project access gates; signal quality via suiNS/verification, not gatekeeping.
git clone https://github.com/hostit-events/hostit-sui.git
cd hostit-sui
# Move package (from the repo root) — requires the Sui CLI on a testnet env
sui move build
sui move test
# Frontend (from web/) — requires bun
cd web
bun install
cp .env.local.example .env.local # fill in keys for Enoki/social login (optional for local dev)
bun run dev # http://localhost:3000- Branch off
main:git checkout -b fix/short-description(orfeat/…,docs/…,chore/…). - Make focused, surgical changes that match the surrounding code's style and patterns.
- Verify before you commit (see below).
- Open a pull request against
mainwith a clear description of the why.
A change is not ready until these pass:
| Scope | Command | Run from |
|---|---|---|
| Move | sui move build && sui move test |
repo root |
| Frontend types | bunx tsc --noEmit |
web/ |
| Frontend lint | bun run lint |
web/ |
| Frontend unit tests | bun run test |
web/ |
⚠️ Do not runbun run buildwhilebun run devis running — they share.next/and the production build corrupts the dev bundle. Usebunx tsc --noEmitto typecheck instead.
Frontend gates are bunx tsc --noEmit, bun run lint, and bun run test (vitest). There is no browser E2E layer. Move changes must keep the tests/ suites green — add a test_scenario test for new on-chain behavior.
- Conventional commits, scoped:
fix(web): …,feat(move): …,docs: …,chore: …,fix(sponsor): …. Keep the subject imperative and < ~72 chars; put the why in the body. - Keep each commit coherent (one logical change). Group related edits; avoid mixing unrelated concerns.
- Ensure the working tree is clean and all gates pass before requesting review.
- Move code — capabilities replace roles (
PlatformCap,OrganizerCap{event_id}); all timestamps are milliseconds. Prefer narrow scope with explicit follow-ups over speculative generalization. - Gasless transactions — the sponsorable move-call allowlist is server-authoritative in
web/app/api/sponsor/route.ts(mirrored as a client hint inweb/lib/sponsor.ts). If you add a sponsored entry function, add its target to both. - Package versioning — the package is upgraded in place, so types anchor to the version that introduced them. When touching the
predictmodule, usePACKAGE_ID_LATESTfor call targets and the matching pinned constant for its types (seeweb/lib/config.tsandCLAUDE.md). - Deploys are gated upgrades — shipping Move changes uses
sui client upgrade, which a maintainer runs with explicit per-deploy authorization. Don't deploy as part of a PR. SeeDEPLOYING.mdfor the full upgrade procedure.
Open a GitHub issue with: what you expected, what happened, and minimal steps to reproduce (route, wallet state, network). For security-sensitive reports, please contact a maintainer privately rather than filing a public issue.
By contributing, you agree that your contributions are licensed under the project's MIT License.