gtkx README

The project's README from github.com/gtkx-org/gtkx. As one markdown file: README.md.

GTKX

GTKX

The React framework for Linux
Build native apps with React, TypeScript, and Adwaita widgets.

npm version npm downloads Node >= 26.7 License: MPL-2.0 CI status TypeScript

Homepage · Documentation · Examples · Contributing · Sponsor

Start an app

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.

You need Linux, Node.js 26.7 or later, GTK 4.20 or later, libadwaita 1.8 or later, and the native development libraries. Follow Getting Started to install and check them before scaffolding:

npm create gtkx@beta my-app
cd my-app
npm run dev

The native addon ships prebuilt for x64 and arm64 glibc Linux. Other targets require building it from the repository with Rust.

Build with React

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 topBar={<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. They are local to the app, not installed from npm.

Learn GTKX

The Tasks app: an Adwaita window with a sidebar of smart views and colored lists on the left, and a boxed task list on the right.

The Tasks app you build in the tutorial.

Contribute

See CONTRIBUTING.md for setup and checks, the Code of Conduct, and the security policy. Architecture and maintainer procedures are in the contributor docs.

Support GTKX

Contribute through Open Collective to help cover recurring costs. Our funding plan explains expenses, fees, and the operating reserve.

License

MPL-2.0.

gtkx (gtkx-org/gtkx)

Searching Database…

487 ·GitHub
Gtkx
What is this?GTKX is a framework for building native Linux desktop apps with React and TypeScript, rendering real Adwaita and GTK4 widgets instead of a browser-based UI.
Is this a UI toolkit wrapper or a full React renderer?GTKX is a full React reconciler: React state and events drive native Adwaita/GTK widgets directly, and you use Node.js for filesystem and network access instead of a browser DOM.
How do I get an app running?You install the required native libraries, then scaffold a project with the GTKX CLI, which also generates @gtkx/jsx elements and @gtkx/gi bindings local to your app instead of fetching them from npm.
What do I need installed before starting?You need Linux, Node.js 26.7 or later, GTK 4.20 or later, libadwaita 1.8 or later, and the native development libraries; targets outside prebuilt x64/arm64 glibc Linux also require building the native addon with Rust.
Is this ready for production yet?This branch is GTKX 2.0, currently in beta, with the stable release scheduled for 1 December 2026, so expect changes before then.
What is Adwaita, and why does it matter here?Adwaita is GNOME's native design system and widget set; GTKX renders real Adwaita/GTK4 widgets so apps look and behave like native Linux software, not an embedded browser view.
Can I use regular npm packages with GTKX?Yes, any npm package that doesn't require a browser DOM works, since GTKX apps run on Node.js with normal filesystem and network access.
What can I learn from the official tutorial?The docs walk through building a Tasks app end-to-end, covering forms, navigation, animation, styling, testing, and packaging it for distribution.
What are similar projects?juhradial-mx, hearthstone-linux-gui, penguin-mail, gpui-kit, native, proton-native, omarchy-meeting-recorder, wails
Which topics is it in?libadwaita, gnome, gtk4, scaffolding, gtk, desktop-application, gui-framework, jsx, native, testing, desktop, rust
Creator
gtkx-org
Size
75.8 MB
Stars
487
Updated
CommitOct 16Releasev1.6.0Aug 29
Age
1y
Commits · 90 Days