The React framework for Linux
Adwaita and GTK 4 widgets, TypeScript, and Node.js.
Homepage · Documentation · Examples · Contributing · Sponsor
GTKX brings the workflow of modern web development to native GTK and Adwaita apps: declarative UI with React, a dev server with Fast Refresh, native UI tests in Vitest, and Flatpak, Debian, RPM, and AppImage packaging. Why GTKX explains the approach, and Comparisons sets it against GJS, node-gtk, React Native, gtk4-rs and Relm4, and Electron and Tauri.
This branch develops GTKX 2.0, currently in beta. The stable release is scheduled for 1 December 2026. For the current stable release, use the 1.x documentation.
GTKX 2.0 requires Linux, Node.js 26.7 or later, GTK 4.20 or later, libadwaita 1.8 or later, and native development libraries. Follow Getting Started to install and check them before scaffolding:
npm create gtkx@beta my-app
cd my-app
npm run devThe native addon ships prebuilt for x64 and arm64 glibc Linux. Building it from source requires Rust and the workspace prerequisites.
GTKX renders native Adwaita and GTK widgets. Use React state and events to update them, Node.js for filesystem and network access, and npm packages that do not require a browser DOM.
This is a complete entry point in a scaffolded app:
import {
AdwApplication, AdwApplicationWindow,
AdwHeaderBar, AdwToolbarView,
} from "@gtkx/jsx/adw";
import { GtkLabel } from "@gtkx/jsx/gtk";
import { createRoot, quit } from "@gtkx/react";
const App = () => (
<AdwApplication>
<AdwApplicationWindow title="My App" onCloseRequest={() => quit()}>
<AdwToolbarView top={<AdwHeaderBar />}>
<GtkLabel>Hello from GTKX</GtkLabel>
</AdwToolbarView>
</AdwApplicationWindow>
</AdwApplication>
);
createRoot().render(<App />);The CLI generates @gtkx/jsx elements and @gtkx/gi bindings from your configured native libraries. These generated packages live in your app’s node_modules.
The Notes app you build in the tutorial.
- Tutorial: build the Notes app, test it, and package it for distribution.
- Guides: forms, navigation, animation, styling, testing, and deployment.
- API reference: GTKX package exports. Widget props are documented in the generated
.gtkx/reference/in your app. - Examples: a counter, a WebKitGTK browser, ports of the GTK and libadwaita demos, spring animations, navigation, and Storybook stories.
Apps created with create-gtkx already depend on the packages they need to run and test. Add libraries as your app needs them.
| Package | Description |
|---|---|
| Apps | |
create-gtkx |
Create native GTK and Adwaita apps with React and GTKX. |
@gtkx/react |
React renderer for native GTK and Adwaita apps. |
@gtkx/cli |
Development and packaging commands for GTK apps built with GTKX. |
@gtkx/config |
Typed configuration for GTK apps built with GTKX. |
| Libraries | |
@gtkx/components |
GTK collection views, selection controls, and toasts for React. |
@gtkx/css |
CSS-in-JS styling for GTK widgets in GTKX. |
@gtkx/navigation |
React Navigation navigators for GTK and Adwaita apps. |
@gtkx/forms |
React Hook Form controls for GTK and Adwaita apps. |
@gtkx/animated |
React Spring animations for GTK widgets in GTKX. |
@gtkx/i18n |
Gettext localization for GTK apps through react-i18next. |
@gtkx/cairo |
Cairo drawing for GTK apps built with GTKX. |
@gtkx/gl |
OpenGL 4.6 core bindings for GTK GL areas in GTKX. |
| Testing and tools | |
@gtkx/testing |
Test GTKX apps against real GTK widgets. |
@gtkx/vitest |
Vitest plugin that runs GTK tests in isolated headless displays. |
@gtkx/storybook |
Native Adwaita explorer for Storybook stories of GTKX components. |
@gtkx/mcp |
MCP server that inspects running GTKX apps and their generated bindings. |
| Bindings and internals | |
@gtkx/codegen |
Generate TypeScript and JSX bindings for GTK and GObject libraries. |
@gtkx/runtime |
Runtime for generated GTK and GObject Introspection bindings in GTKX. |
@gtkx/native |
Node.js addon that calls GTK and other C libraries for GTKX. |
@gtkx/utils |
Shared Node.js utilities used by GTKX packages. |
See CONTRIBUTING.md for setup and checks, the Code of Conduct, and the security policy. Architecture and maintainer procedures are in the contributor docs.
Contribute through Open Collective to help cover recurring costs. Our funding plan explains expenses, fees, and the operating reserve.
Why GTKX credits the projects GTKX builds on.