gtkx

gtkx is a framework for building native GTK4/libadwaita desktop applications with React, TypeScript, and JSX. You write declarative JSX whose element types are GTK widget names; a custom react-reconciler maps that tree to live GObject instances, while a Rust napi addon owns the single GLib main-loop thread and performs every call into GTK. A build-time generator turns GObject-Introspection (GIR) XML into typed bindings, JSX element types, and reconciler metadata, and a Vite-based CLI provides scaffolding, a hot-reloading dev server, single-file production bundling, and GTK-asset integration.

Homepage: gtkx.dev

Prerequisites

This is a Linux desktop framework, not a browser/DOM renderer. You need:

• Node.js — the engines floor is Node >=24.
• pnpm — the workspace package manager, provisioned via Corepack from the packageManager field.
• Rust toolchain — 2024 edition with a C linker, plus the napi-rs CLI and Node N-API headers, to compile the native addon. A nightly toolchain is additionally required for the coverage, asan, and miri paths.
• libffi — for dynamic CIF construction and closures in the native addon.
• GTK4 and libadwaita development libraries, plus the broader GNOME library set the examples use (GtkSourceView, WebKitGTK, VTE, GStreamer, etc.), with pkg-config.
• GLib/GObject shared libraries present at build and run time; gtkx resolves GTK symbols dynamically by name.
• GObject-Introspection development data and system GIR files (read by codegen), plus glib-compile-resources and glib-compile-schemas for asset compilation.
• A headless Wayland compositor (Weston, or Sway when GTKX_COMPOSITOR=sway) and software GL/Vulkan rasterization to run GTK tests and benches without a GPU.
• git, for repository initialization during scaffolding.

For the containerized CI path you additionally need Docker; the CI image pins the full GTK/Rust/Node toolchain.

Getting started

git clone https://github.com/gtkx-org/gtkx.git
cd gtkx
corepack enable
pnpm install
pnpm build

pnpm build runs the Rust native-build and @gtkx/cli#codegen first (hard Turbo upstreams), so the first build compiles the addon and generates the @gtkx/gi/@gtkx/jsx binding stores before any TypeScript package builds.

Common commands

All root scripts run through Turbo over the workspace (the root meta-package is excluded with --filter=!gtkx).

| Command | Description | | --- | --- | | pnpm build | Build all workspace packages (runs codegen + native-build first). | | pnpm --filter <pkg> dev | Start a package/example dev server (hot-reloading gtkx dev); see Running the examples. There is no root dev script. | | pnpm test | Run the Vitest workspace plus per-package test scripts. | | pnpm typecheck | Type-check every package via tsc -b --emitDeclarationOnly across the reference graph. | | pnpm lint | Full quality gate: ts-reference drift check, biome, knip (default + production), dependency-cruiser, plus per-package lint (Rust fmt/clippy on native). | | pnpm codegen | Generate/refresh the .gtkx GIR and JSX binding stores consumed by other packages. | | pnpm coverage | Aggregated v8 lcov coverage (TS) plus native Rust coverage. | | pnpm sync:ts-refs | Rewrite TypeScript project references from package.json deps and format them (add --check to fail on drift). | | pnpm asan / pnpm miri / pnpm bench | Native AddressSanitizer suite, Miri marshalling subset, and CodSpeed benchmarks under the headless compositor. | | pnpm release | Build, inject README into published packages, stage native artifacts, and publish to npm. | | pnpm publish-test | Publish to an ephemeral Verdaccio registry, then scaffold, build, typecheck, and test a consumer app end-to-end. |

To run tests for a single package, filter through Turbo or pnpm, for example:

pnpm --filter @gtkx/ffi test
pnpm --filter @gtkx/react test
pnpm --filter @gtkx/cli build

Running the examples

Each example exposes the standard dev, build, and start scripts that wrap the CLI (gtkx dev / gtkx build / node dist/bundle.js).

# Counter app demonstrating the basics
pnpm --filter hello-world dev

# Notes app from the tutorial (uses @gtkx/css and @gtkx/animate, GSettings via #data)
pnpm --filter tutorial dev

# GTK4 widget showcase (the React port of the official gtk-demo; the only example with tests)
pnpm --filter gtk-demo dev
pnpm --filter gtk-demo coverage

# Simple browser using WebKitWebView
pnpm --filter browser dev

Build and run any example's production bundle:

pnpm --filter hello-world build
pnpm --filter hello-world start

The tutorial additionally packages as a single executable (pnpm --filter tutorial build:sea) and as a Flatpak (pnpm --filter tutorial build:flatpak); these need esbuild, postject, and a Flatpak toolchain.

Gotchas

• codegen and native-build come first. A clean checkout cannot type-check or build any TypeScript package until the Rust addon is compiled and codegen has produced .gtkx; both are hard Turbo upstreams. pnpm lint first creates the .gtkx symlink that knip and dependency-cruiser resolve against.
• Generated packages are not hand-edited. @gtkx/gi, @gtkx/jsx, and the generated @gtkx/gl sources come from @gtkx/codegen. Change the emitters or gtkx.config.ts and regenerate (pnpm codegen); the store swap is atomic, so partial writes never appear.
• GTK tests/benches need a headless display. Running native test/coverage/asan or the GTK suites outside the headless wrapper fails to initialize a display; the harness provisions a Wayland compositor with software rendering. Native tests run single-threaded because GTK requires a single owning thread.
• The native runtime is single-use. All GObject/GTK mutation runs only on the single gtkx-glib thread; native init is one-shot and quit is terminal, so a process cannot restart the runtime. Importing @gtkx/ffi starts the GLib main loop and registers a process exit handler.
• Project references track deps. TypeScript references are generated from package.json dependency fields by sync-ts-references; hand-editing them is reported as drift by the --check run in lint. Change deps, then run pnpm sync:ts-refs.
• @gtkx/testing cleanup is not automatic. Consumers must register cleanup() (the e2e setup wires it into afterEach/afterAll), or leaked windows persist across tests.
• The dev loop restarts via exit code 75. The dev supervisor and runner signal restart intent purely through process exit code 75; Fast Refresh applies only to SSR-transformed project files where every export looks like a React component, otherwise the whole process restarts.

Documentation

Architecture and subsystem docs live under docs/:

• docs/architecture.md — architecture overview and layer stack.
• docs/rendering.md — the render and event pipeline.
• docs/codegen.md — the GIR/Khronos code generator and the runtime contract.
• docs/cli.md — the CLI and project workflow.
• docs/styling.md — styling, animation, and GL.
• docs/mcp.md — the MCP server.
• docs/testing.md — the testing architecture.
• docs/build-system.md — the build system and quality tooling.

For an agent-oriented index of packages and the hard build rules, see CLAUDE.md.