Contributing
GUIJam is a pnpm workspace for the TypeScript packages and a Cargo workspace for the Rust daemon, in one repository: github.com/francistinao/gui-jam.
Set up#
You need Node 22.18 or later, pnpm 10, and Rust. The pinned toolchain in rust-toolchain.toml is installed by rustup.
git clone https://github.com/francistinao/gui-jam.git
cd gui-jam
pnpm install
pnpm exec playwright install chromium
cargo build -p gjd-daemon
pnpm buildTry your checkout#
Run the example app against your checkout:
GUIJAM_GJD_BIN=$PWD/target/debug/gjd pnpm --filter small-react-tailwind4 devTry GUIJam in one of your own Vite apps without changing its tracked files, then remove it again:
scripts/try-guijam.sh setup ../my-app
scripts/try-guijam.sh clean ../my-appCreate fresh apps for every supported framework with their official starters and a real guijam init, then test them all:
scripts/playground.sh
pnpm test:playgroundTry the setup CLI on any app:
GUIJAM_GJD_BIN=$PWD/target/debug/gjd node packages/guijam/dist/cli.js init --skip-install --cwd ../my-appRun the checks#
Run every check the CI runs, stopping at the first failure:
scripts/gate.sh| Command | What it does |
|---|---|
pnpm build | Builds every package; the fixtures use the built output |
pnpm check | Lints and formats with Biome |
pnpm typecheck | Type-checks the packages and the fixtures |
pnpm test | Runs the unit tests (Vitest) |
pnpm test:e2e | Builds, then runs the browser tests (Playwright) against the fixtures |
pnpm test:playground | Builds, then runs the browser tests against the apps scripts/playground.sh creates |
pnpm contracts:gen | Regenerates the TypeScript and Rust types from contracts/ |
pnpm contracts:check | Fails if the generated contracts are out of date |
cargo fmt --all --check | Checks Rust formatting |
cargo clippy --workspace --all-targets -- -D warnings | Lints the Rust code |
cargo test --workspace | Runs the Rust tests |
scripts/smoke-package.sh | Packs guijam, installs it outside the workspace, and checks that it loads and type-checks |
cargo run -p gjd-daemon -- provider list | Lists the AI CLIs as the daemon sees them |
cargo run -p gjd-daemon -- provider test claude-code --runs 5 | Runs a real CLI five times and reports timings (spends tokens) |
The browser tests use a stand-in for Claude Code, so they spend no tokens.
Repository layout#
| Path | What it is |
|---|---|
packages/guijam | The published package: guijam/vite, guijam/nuxt, guijam/astro, guijam/next and the guijam CLI |
packages/vite-plugin | Source locations, in-memory previews, hot-update tracking, and the Next.js loader and relay |
packages/overlay | The browser widget (React in a shadow root) |
packages/contracts-ts | TypeScript types generated from contracts/ |
contracts/ | JSON Schemas shared by every process |
crates/gjd-core | Source inspection, the patch engine and the journal |
crates/gjd-providers | Provider CLI adapters |
crates/gjd-daemon | The gjd binary |
fixtures/ | Apps the tests run against |
tests/e2e/ | Playwright suites |
tests/playground/ | Playwright suite for the apps scripts/playground.sh creates |