Skip to content
gtkx-orgPublic

About

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

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

495 stars

Watchers

1 watching

Forks

Latest commit

 

History

1,696 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

GTKX

The React framework for Linux
Adwaita and GTK 4 widgets, TypeScript, and Node.js.

npm version npm downloads Node.js version License: MPL-2.0 CI status

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.

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.

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 dev

The native addon ships prebuilt for x64 and arm64 glibc Linux. Building it from source requires Rust and the workspace prerequisites.

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 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.

Learn GTKX

The Notes app: an Adwaita window with a list of notes on the left and a note rendered as Markdown on the right.

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.

Packages

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.

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.

Credits

Why GTKX credits the projects GTKX builds on.

License

MPL-2.0.

About

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

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

495 stars

Watchers

1 watching

Forks

Releases

Sponsor this project

Packages

Used by

Contributors

Languages