KO | EN

GitLite

Minimalist Open Source Repository Search Engine

gitlite — search

#typescript #ai-agents #cli #open-source #ai #claude-code #codex #developer-tools #react #windows #deepseek-harness #ai-agent

gtkx

★ 369 Open GitHub ↗

The React framework for Linux. Write native Linux applications with React and TypeScript.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

The React framework for Linux. 
 Write native Linux applications with React and TypeScript.
 Built on the GNOME stack and standard web tooling.

<a href="https://gtkx.dev">Homepage</a> &middot;
 <a href="https://gtkx.dev/guide/getting-started">Documentation</a> &middot;
 <a href="https://github.com/gtkx-org/gtkx/tree/main/examples">Examples</a> &middot;
 <a href="https://github.com/gtkx-org/gtkx/blob/main/CONTRIBUTING.md">Contributing</a>

---

The Tasks app you build in the <a href="https://gtkx.dev/tutorial/">tutorial</a>.

## Demo

The intrinsic elements in this snippet render GTK4 widgets, and ordinary React hooks and events drive them:

```tsx
import * as Gtk from "@gtkx/gi/gtk";
import { GtkApplication, GtkApplicationWindow, GtkBox, GtkButton, GtkLabel } from "@gtkx/jsx/gtk";
import { createRoot, quit } from "@gtkx/react";
import { useState } from "react";

const Counter = () => {
  const [count, setCount] = useState(0);

return (
 <GtkApplicationWindow
 title="Hello GTKX"
 defaultWidth={400}
 defaultHeight={300}
 onCloseRequest={quit}
 >
 <GtkBox
 orientation={Gtk.Orientation.VERTICAL}
 spacing={20}
 marginTop={40}
 marginBottom={40}
 marginStart={40}
 marginEnd={40}
 valign={Gtk.Align.CENTER}
 halign={Gtk.Align.CENTER}
 >
 <GtkLabel cssClasses={["title-1"]}>Welcome to GTKX!</GtkLabel>
 <GtkLabel cssClasses={["title-2"]}>{`Count: ${count}`}</GtkLabel>
 <GtkButton
 label="Increment"
 onClicked={() => setCount((c) => c + 1)}
 cssClasses={["suggested-action", "pill"]}
 />
 </GtkBox>
 </GtkApplicationWindow>
 );
};

const App = () => (
 <GtkApplication>
 <Counter />
 </GtkApplication>
);

createRoot().render(<App />);
```

This is the [`hello-world`](https://github.com/gtkx-org/gtkx/tree/main/examples/hello-world) example, with `app.tsx` and `index.tsx` combined into a single snippet. `@gtkx/gi` and `@gtkx/jsx` are per-project bindings generated by the CLI, not packages you install from npm.

## Why GTKX

### A declarative layer for the GNOME stack

GTK4 is mature, and GtkBuilder XML can lay out a static interface, but nothing re-renders that interface when your application state changes, and nothing hot-reloads it as you work. GTKX adds that missing layer, and the tooling around it, on top of the stack you already know:

- a React reconciler that exposes every GObject as a JSX element,
- a CLI for scaffolding, development, and production builds,
- a dev server with Fast Refresh that patches your running UI in place,
- CSS-in-JS styling and high-level list, grid, and dialog components,
- a Testing Library-style API for querying and driving your widgets in tests,
- and a Model Context Protocol (MCP) server that exposes your live app to AI agents.

### The full GNOME API surface

React Native and similar frameworks hide the native toolkit so one API can run everywhere. GTKX exposes it: GTK4, Adwaita, and any other GObject-Introspection library on your system. Linux-only by design.

### Why Node.js, and why generated bindings

GTKX runs on Node.js, which puts native modules, the npm ecosystem, and the tooling built for Node.js APIs within reach. GJS is GNOME's own runtime, built on SpiderMonkey rather than V8; node-gtk runs on Node.js but is lightly maintained, on the older nan/V8 ABI rather than N-API, and still centered on GTK3. The [Why GTKX guide](https://gtkx.dev/guide/why-gtkx) covers what running on Node.js means day to day.

GTKX generates the TypeScript types and the native FFI calls from the same GObject-Introspection data, so the types cannot drift from the calls they back. Codegen covers the whole GTK4 and Adwaita surface.

At runtime, the native Rust core calls straight into the system GTK4, Adwaita, and GLib libraries through libffi, without loading libgirepository at all.

## Quick start

GTKX is Linux-only and needs Node.js 24 or later. See [Requirements](#requirements).

Scaffold a new app with the `create-gtkx` initializer:

```sh
npm create gtkx
```

The same command works with other package managers: `pnpm create gtkx` or `yarn create gtkx`.

Then run your new app:

```sh
cd my-app
npm run dev
```

To go further, follow the [tutorial](https://gtkx.dev/tutorial/).

## Documentation

The documentation at **[gtkx.dev](https://gtkx.dev)** includes a step-by-step tutorial that builds a complete GNOME app, from scaffolding to packaging and shipping, plus guides and a full API reference.

**[Read the docs &rarr;](https://gtkx.dev/guide/why-gtkx)**

## Requirements

GTKX is Linux-only. You need:

- Linux with the GTK4 (4.20 or later) and GLib development libraries, plus Adwaita (1.8 or later) once your project binds `Adw-1`
- Node.js 24 or later

The `@gtkx/native` addon ships prebuilt for x64 and arm64 glibc Linux; other targets need to build it from the GTKX repository, which requires a Rust toolchain.

## Examples

Explore the [example apps](https://github.com/gtkx-org/gtkx/tree/main/examples):

- [`hello-world`](https://github.com/gtkx-org/gtkx/tree/main/examples/hello-world): the counter above.
- [`gtk-demo`](https://github.com/gtkx-org/gtkx/tree/main/examples/gtk-demo): a React port of the official GTK4 widget showcase, covering lists, dialogs, gestures, CSS, and OpenGL.
- [`browser`](https://github.com/gtkx-org/gtkx/tree/main/examples/browser): a WebKitWebView-based web browser.
- [`tutorial`](https://github.com/gtkx-org/gtkx/tree/main/examples/tutorial): the Tasks app the documentation builds.

## Status

GTKX is stable and ready for production use.

## Contributing

Contributions are welcome. See [CONTRIBUTING.md](https://github.com/gtkx-org/gtkx/blob/main/CONTRIBUTING.md), the [Code of Conduct](https://github.com/gtkx-org/gtkx/blob/main/CODE_OF_CONDUCT.md), and the [security policy](https://github.com/gtkx-org/gtkx/blob/main/SECURITY.md). Building the repo needs Node.js 24 or later, pnpm, and a Rust toolchain.

## License

GTKX is licensed under [MPL-2.0](https://github.com/gtkx-org/gtkx/blob/main/LICENSE).

gtkx

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README