Contributing

Rezi welcomes issues and pull requests. This page summarizes the local workflow. For behavior changes, the canonical testing policy is: - Testing Policy

Rezi welcomes issues and pull requests. This page summarizes the local workflow. For behavior changes, the canonical testing policy is:

Testing Policy

Before starting implementation, review the mandatory guides:

Prerequisites

Node.js 18+ (18.18+ recommended)
npm (workspace root)
Rust stable (only if you build @rezi-ui/native)
Python 3 (docs build)

Local setup

npm ci
npm run build

Typical checks

npm run typecheck
npm run lint
npm test
npm run docs:build

Testing requirements

When you change behavior:

test expected behavior, not current implementation shape
use the lowest fidelity that proves the contract, but no lower
include PTY evidence when terminal-visible behavior cannot be proven safely by semantic or replay tests
cover degraded-capability and failure paths when the contract depends on them
fix the implementation when a valid behavior-first test fails, unless the contract is genuinely under-specified

Hook and API changes

For public hook changes, update docs/guide/hooks-reference.md and docs/guide/composition.md in the same PR.
For animation hook changes (useTransition, useSpring, useSequence, useStagger) or ui.box transition behavior, also update docs/guide/animation.md and docs/widgets/box.md.
Add deterministic lifecycle tests (mount, dependency change, unmount cleanup, stale async result guards).
If the hook depends on runtime capabilities, keep adapters in runtime packages (@rezi-ui/node, etc.), not in @rezi-ui/core.

For ui.virtualList behavior changes, also run focused suites before full tests:

node --test packages/core/src/widgets/__tests__/virtualList.contract.test.ts
node --test packages/core/src/layout/__tests__/layout.overflow-scroll.test.ts
node --test packages/core/src/app/__tests__/widgetRenderer.integration.test.ts

HSR change checklist

If your change touches app.view, route integration, reconciliation identity, createNodeApp({ hotReload }), or createHotStateReload:

add app runtime tests for app.replaceView(...) / app.replaceRoutes(...) behavior
verify widget local state survives reload with stable ids or keys
verify failure paths keep the previous working view or routes
update user docs when API or limitations change
manually run npm run hsr:demo:widget once and confirm in-app code-editor save (self-edit-code + F6/Ctrl+O or save button + Enter) triggers reload without process restart

If your change touches code-editor syntax behavior (syntaxLanguage, tokenizer exports, or renderer token painting):

add or extend unit tests for built-in language presets and custom tokenizer override paths
verify fallback behavior for unsupported language names (plain)
update widgets/code-editor and packages/core API docs