Tech Stack
This page maps the technologies and packages on main. The architecture overview traces how they communicate. Dependency ranges live in package manifests and the shared pnpm catalog. The pnpm and Cargo lockfiles record the resolved dependency versions.
Languages and execution
| Technology | Role in GTKX |
|---|---|
| TypeScript 6 | Implements the React renderer, generated bindings, runtime wrappers, CLI, testing tools, and higher-level packages. |
| React 19 | Supplies components, hooks, state, context, and scheduling. react-reconciler connects React commits to GTKX's native element tree. |
| Node.js 26.7 or later | Runs application JavaScript, loads the native addon, and provides the Node APIs used by applications and tooling. |
| Rust, edition 2024 | Implements the native bridge, native value conversion, object lifetime handling, callbacks, and integration with the GLib main context. |
| C ABI and GObject Introspection | Describe the native functions, types, properties, signals, and ownership information that code generation translates into JavaScript and TypeScript. |
The framework workspace packages use ECMAScript modules and NodeNext module resolution. The website and generated compiler configuration use bundler resolution. The shared compiler configuration enables strict checking, exact optional properties, checked indexed access, and project references. Library builds emit JavaScript, declarations, and source maps into each package's dist/ directory. A source export condition lets workspace tooling resolve package source during development.
Rust is pinned by rust-toolchain.toml. The addon is built with napi-rs as a Node-API module. It uses libloading to resolve native libraries and libffi to invoke functions described by generated metadata. The glib crate provides the Rust integration with GLib. Prebuilt native npm packages target x64 and arm64 Linux with glibc.
Native platform
| Library or subsystem | Responsibility |
|---|---|
| libadwaita | Application windows, navigation, dialogs, preferences, adaptive layouts, and GNOME presentation patterns. |
| GTK4 and GDK | Widgets, layout, input, accessibility, drawing surfaces, and display integration. |
| GLib, GObject, and GIO | Main contexts, reference-counted objects, properties, signals, files, settings, D-Bus, and asynchronous operations. |
| Cairo | Immediate-mode 2D drawing exposed through @gtkx/cairo. |
| OpenGL | GPU drawing exposed through @gtkx/gl and GTK's GL areas. |
| GtkSourceView and WebKitGTK | Additional libraries selected by the repository's configuration for source editing and embedded web content. |
| Wayland and D-Bus | Isolated displays and session services for headless development and tests. |
The baseline application requirements are GTK 4.20 and libadwaita 1.8 or later. Code generation reads the GIR files installed on the development machine, so the available bindings follow that machine's libraries and the project's configuration. The repository selects GtkSourceView 5 and WebKitGTK 6.0 in addition to the default libraries; contributing to the whole workspace requires their development files too.
The generated @gtkx/gi and @gtkx/jsx packages belong to each project. Their namespace exports provide native classes and functions, and JSX elements, respectively. They are generated by gtkx codegen and linked into the project's node_modules; they are not published npm packages to install separately. See Configuration and Codegen.
Package map
All paths below are relative to the repository root. Package names normally match their directory under packages/; packages/create-gtkx publishes as create-gtkx. The map describes current package contents; Development Principles defines their required boundaries.
Core and generation
| Package | Responsibility |
|---|---|
@gtkx/native | Rust addon and JavaScript bootstrap for calls into native libraries, object lifetimes, callbacks, and main-context integration. |
@gtkx/runtime | JavaScript wrappers and conversions used by generated bindings, including GObjects, boxed values, signals, variants, and subclassing. |
@gtkx/codegen | Parses GIR and Khronos metadata and generates bindings, JSX definitions, and reference documentation. |
@gtkx/config | Loads and validates project configuration and supplies element and prop mappings. |
@gtkx/react | React renderer, native element tree, application roots, portals, and integration with GTKX configuration and runtime. |
@gtkx/utils | Shared utilities used across the runtime and toolchain. |
Application libraries
| Package | Responsibility and upstream foundation |
|---|---|
@gtkx/components | Collection views, dropdowns, combo rows, and toast helpers built on the GTKX renderer. |
@gtkx/navigation | Stack, tab, drawer, and split-view navigation, using React Navigation's core and routers with Adwaita containers. |
@gtkx/forms | React Hook Form integration for native controls. |
@gtkx/animated | React Spring integration with the native frame clock. |
@gtkx/css | CSS-in-JS using Emotion serialization and Stylis, installed into GTK's CSS system. |
@gtkx/i18n | i18next and react-i18next integration with GNU gettext catalogs. |
@gtkx/cairo | Typed wrappers around Cairo drawing APIs. |
@gtkx/gl | Generated OpenGL bindings and helpers for GTK GL areas. |
Development and verification
| Package | Responsibility |
|---|---|
@gtkx/cli | gtkx dev, build, deploy, codegen, docs, storybook, mcp, create, and cleanup; integrates Vite with the native runtime. |
create-gtkx | Interactive and noninteractive project scaffolding and starter templates. |
@gtkx/storybook | Native story explorer, controls, actions, and reusable Component Story Format fixtures. |
@gtkx/mcp | MCP server for generated references and inspection and interaction with a running application. |
@gtkx/testing | Rendering, accessible widget queries, user input, assertions, and screenshots for tests. |
@gtkx/vitest | Worker preload and isolated headless display and session-bus infrastructure. |
@gtkx/e2e | Private integration suite spanning the renderer, generated bindings, runtime, native bridge, and testing APIs. |
@gtkx/eslint | Private shared ESLint configuration and custom repository rules. |
Build and development tools
pnpm manages the workspace and its shared dependency catalog. Nx discovers TypeScript, ESLint, and Vitest targets, combines them with explicit package targets, orders their dependencies, and caches eligible results. pnpm build, pnpm test, pnpm lint, and pnpm typecheck are entry points into that task graph.
The CLI uses Vite for application development and bundling. Its plugin stack integrates generated bindings, native assets, styles, settings, localization, and the application runtime. SWC transforms TypeScript and JSX for Fast Refresh during development; the React Compiler runs through Babel, and React Fast Refresh updates components in a running development session.
Vitest runs the JavaScript test suites. GTKX's plugin gives workers real headless Wayland displays, while the testing package works with native widgets and accessibility information. Native integration fixtures are built with Meson and Ninja. V8 coverage and an additional subprocess coverage pass account for JavaScript executed by tests and CLI child processes. The native sanitizer target uses AddressSanitizer and LeakSanitizer.
ESLint checks TypeScript and JavaScript, Knip checks unused code and dependencies, and Rust uses rustfmt and Clippy. The exact commands and target dependencies are declared in nx.json and each package's package.json.
Documentation, examples, and distribution
The website uses VitePress, Vue, and Shiki. Its prose lives under website/, and TypeDoc with its Markdown and VitePress integrations generates the API reference from package output. website/versions.json controls version labels, URL prefixes, and whether an API reference comes from the working tree or a pinned release tag.
examples/ contains runnable applications, the GTK demo, and native stories. Most examples consume workspace packages. examples/tutorial is deliberately excluded from the pnpm workspace so the tutorial can also verify installation and execution as an external consumer.
GitHub Actions runs checks, prepares releases, publishes packages, and deploys the website to GitHub Pages. Nx version plans record published-package changes. Consumer validation uses a private Verdaccio registry to test the packages produced by the repository. Application distribution through gtkx deploy supports Flatpak, Debian packages, RPM packages, and AppImage; see Deploying for those application workflows.
Continue with Development Setup to build the workspace, or Testing to choose a verification path.