Build

This page covers how to build Rezi from source, including the TypeScript packages, native addon, and documentation site.

Prerequisites

For the native addon (optional):

For documentation (optional):

Initial Setup

Clone the repository and initialize submodules:

git clone https://github.com/RtlZeroMemory/Rezi.git
cd Rezi
git submodule update --init --recursive

The vendor/zireael submodule contains the Zireael C engine source. It must be present for native addon builds, but is not required for TypeScript-only development.

Install all dependencies:

npm ci

This installs dependencies for all workspace packages (packages/* and examples/*) in a single operation. Rezi uses npm workspaces (not pnpm or yarn).

TypeScript Build

Build the TypeScript projects referenced by the root tsconfig.json:

npm run build

This runs tsc -b (TypeScript project build mode) across the root project references: packages/create-rezi, packages/core, packages/node, packages/testkit, packages/jsx, and examples/*. Packages like @rezi-ui/native and @rezi-ui/bench are built separately.

TypeScript build mode is incremental, so subsequent builds after the first are fast -- only changed files and their dependents are recompiled.

The build output lands in dist/ directories within each package:

packages/core/dist/
packages/node/dist/
packages/jsx/dist/
packages/testkit/dist/
packages/create-rezi/dist/
examples/hello-counter/dist/
examples/raw-draw-demo/dist/

Incremental Rebuilds

For iterative development, run the same command:

npm run build

TypeScript's incremental build mode (tsc -b) uses .tsbuildinfo files to skip unchanged projects. A full rebuild from scratch takes several seconds; incremental rebuilds typically complete in under a second.

Type Checking in CI

To run the TypeScript build with machine-readable error output (useful in CI):

npm run typecheck

This runs tsc -b --pretty false for the same root project references with colorized output disabled for easier log parsing. It produces the same .js and .d.ts output as npm run build.

Native Addon Build

The native addon (@rezi-ui/native) wraps the Zireael C engine via napi-rs. Most users do not need to build it -- prebuilt binaries are published for common platforms (see Native addon).

To build from source:

npm run build:native

This is a shorthand for:

npm -w @rezi-ui/native run build:native

The build compiles both the Rust napi-rs glue and the vendored C engine source. The resulting .node binary is placed in packages/native/.

After building, run the smoke test to verify:

npm run test:native:smoke

Documentation Build

Rezi's documentation is built with MkDocs Material. A helper script handles Python virtual environment setup automatically.

Local Development Server

bash scripts/docs.sh serve

This command:

1. Creates a Python virtual environment at .venv-docs/ (if it does not exist).
2. Installs dependencies from requirements-docs.txt.
3. Generates TypeDoc API reference output.
4. Starts the MkDocs development server with live reload.

Production Build

bash scripts/docs.sh build

Builds the static site into out/site/ with --strict mode enabled (all warnings become errors). The TypeDoc API reference is staged into the site at api/reference/.

Requirements

The Python dependencies are pinned in requirements-docs.txt:

mkdocs>=1.6,<1.7
mkdocs-material>=9.5,<10
pymdown-extensions>=10.8,<11

Formatting and Linting

Rezi uses Biome (v1.9.4) for formatting and linting:

# Format all files in-place
npm run fmt

# Check for lint issues
npm run lint

See the Style guide for details on coding conventions.

Common Build Issues

Missing submodules

If you see errors about missing vendor files:

git submodule update --init --recursive

Stale incremental build

If TypeScript reports errors that do not match the source, delete build caches:

rm -rf packages/*/dist packages/*/.tsbuildinfo
npm run build

Native build fails with missing C compiler

The native addon build requires a working C toolchain. On Linux:

sudo apt-get install build-essential

On macOS, install Xcode Command Line Tools:

xcode-select --install

Python/MkDocs not found

The docs build requires Python 3. If python3 is not on your PATH, set the PYTHON environment variable:

PYTHON=/usr/bin/python3.11 bash scripts/docs.sh serve

CI Scripts

The repository includes several CI-oriented scripts in scripts/:

See Also

• Install
• Repo layout
• Testing