Thanks for wanting to help! @clack/ui is still an early alpha, so APIs change and whole files get rewritten. If you're planning anything bigger than a small fix, open an issue or say hi on Discord first. That way nobody loses a weekend to code that's about to move.
Fork the repo, then clone your fork:
git clone https://github.com/<your-username>/ui.git
cd uiYou need the exact Node and pnpm versions listed under devEngines in the root package.json. This part is picky. The wrong Node stops pnpm install right away, and pnpm 11 fails on the node-pty build.
Any version manager works. If you use mise, which is what our lint, format, and test checks use, export MISE_IDIOMATIC_VERSION_FILE_ENABLE_TOOLS=node,pnpm and run mise install so it reads those versions from package.json.
Then install the dependencies:
pnpm installRun these from the repo root. You don't need to build before you run the tests.
| Command | What it does |
|---|---|
pnpm test |
Runs every test |
pnpm test packages/ui/src/layout.test.ts |
Runs one test file |
pnpm lint |
Runs the linter |
pnpm format |
Formats the code |
pnpm format:check |
Checks the formatting and changes nothing |
pnpm build |
Builds the packages |
pnpm bench |
Runs the benchmarks |
The benchmarks take a few minutes, so you only need them for changes that could affect rendering speed.
All the code lives in packages/ui.
srchas the runtime. Start withcreateUIinsrc/ui.ts.- Tests sit next to the code as
*.test.ts. testhas the test helpers.benchhas the benchmarks, and its README explains what they measure.
To test what ends up on the screen, use createTestUI from test/ui.ts. It runs the UI against a fake terminal in the same process, so you can read the screen, type, and press keys:
await using ui = await createTestUI({ cols: 12, rows: 2 });
ui.document.documentElement.appendChild(ui.document.createTextNode('hello'));
await expect.poll(() => ui.terminal.screen.getLines()).toEqual(['hello', '']);Use expect.poll here, because the screen doesn't update the moment you change the document.
Before you push, make sure these pass:
pnpm lint
pnpm format:check
pnpm testCI runs the same three on every pull request, along with the benchmarks and a workflow that publishes a preview build. In your PR, tell us why the change is needed and link the issue if there is one.
Everyone here follows the Bombshell code of conduct. By contributing, you agree that your work is licensed under the MIT license.
Stuck on something? Come ask on Discord.