Skip to content
NEWGTKX 2.0 beta is available

The React framework for Linux

Build native Adwaita and GTK apps with the workflow of modern web development: React components, Fast Refresh, native UI tests, and packaging, on Node.js. Why GTKX

npm create gtkx@2.0.0-beta.14

Prefer the stable release? Use GTKX 1.6 stable.

<GtkBox orientation={Gtk.Orientation.VERTICAL}>
  <
    placeholderText={t("Search notes")}
    text={query}
    onSearchChanged={(entry) =>
      setQuery(entry.getText())
    }
  />
  {tags.length > 0 && (
    <
      tags={tags}
      tag={tag}
      onChange={setSelectedTag}
    />
  )}
  <<Note>
    items={shown.map((note) => ({
      id: note.name,
      value: note,
    }))}
    selectionMode={Gtk.SelectionMode.SINGLE}
    renderItem={({ item }) => (
      < note={item} />
    )}
  />
</GtkBox>
<GtkScrolledWindow vexpand>
  <
    ref={setView}
    accessibleLabel={t("Note text")}
    wrapMode={Gtk.WrapMode.WORD_CHAR}
    buffer={
      <GtkSourceBuffer
        text={text}
        language={}
        styleScheme={styleScheme}
        onChanged={(buffer) => {
          onChange(
            buffer.getText(
              buffer.getStartIter(),
              buffer.getEndIter(),
              false,
            ),
          );
        }}
      />
    }
  />
</GtkScrolledWindow>
<
  onClosed={onClose}
  title={t("Preferences")}
>
  <AdwPreferencesPage title={t("General")}>
    <AdwPreferencesGroup title={t("Appearance")}>
      <
        title={t("Style")}
        items={colorSchemeItems()}
        selectedId={colorScheme}
        onSelectionChanged={(id) => {
          const scheme = toColorScheme(id);
          if (scheme !== undefined) {
            setColorScheme(scheme);
          }
        }}
      />
    </AdwPreferencesGroup>
    < title={t("Storage")}>
      < onError={onError} />
    </AdwPreferencesGroup>
  </AdwPreferencesPage>
</AdwPreferencesDialog>
The Notes app from the GTKX tutorial: a sidebar with a search entry, a tag filter and a list of notes, next to a note rendered as Markdown.The Notes app from the GTKX tutorial: a sidebar with a search entry, a tag filter and a list of notes, next to a note rendered as Markdown.

Point at a component in the code to find it in the window.The Notes app you build in the tutorial

The workflow

From npm create to an installable package

Each step uses tools web developers already know, on real GTK and Adwaita widgets.

Develop

Edits land in the open window

Fast Refresh applies most edits to the open window and keeps its state.

The dev loop
src/preview/markdown-preview.tsx
<GtkBox cssClasses={["card"]}><GtkSeparator orientation={Gtk.Orientation.VERTICAL} />

Saved twice. The code moves into a card, the quote gets its bar, and the note stays open.

The Notes window showing Meeting notes as a rendered preview while two edits are saved: the code block moves into a card, then the quote gets a bar beside it.The Notes window showing Meeting notes as a rendered preview while two edits are saved: the code block moves into a card, then the quote gets a bar beside it.

Develop

Adwaita and GTK widgets as components

Lists, tables, dialogs and adaptive layouts are the toolkit's own. React updates them when state changes.

Components
A window titled ColumnView with a table of four employees in Name and Team columns, sorted by name in ascending order.A window titled ColumnView with a table of four employees in Name and Team columns, sorted by name in ascending order.
The Notes window at 360 pixels wide, collapsed to one pane: Website relaunch open in the editor under a header bar with a back button.The Notes window at 360 pixels wide, collapsed to one pane: Website relaunch open in the editor under a header bar with a back button.

Develop

Types for the libraries you add

Codegen emits typed props, signals, and methods for each native library, such as WebKitGTK.

Codegen

gtkx.config.ts

libraries: ["WebKit-6.0"],

src/app.tsx

<WebKitWebView
  accessibleLabel="Web page"
  onNotifyUri={handleUri}
  onNotifyIsLoading={handleIsLoading}
/>

Develop

Your agent can drive the app

The MCP server lets a coding agent inspect the running app, act on it, and check the result.

MCP
  • gtkx_query_widgetsFind widgets by role, text, accessible name or label
  • gtkx_clickClick a widget
  • gtkx_take_screenshotCapture a window as an image, a saved PNG, or both

Test

Test the real interface

Tests run in Vitest on a private headless display. Find widgets by role and name, click and type, and assert on what the user sees.

Testing

tests/settings-panel.test.tsx

await userEvent.type(name, "Ada");
await userEvent.click(
  screen.getByRole(
    Gtk.AccessibleRole.BUTTON,
    { name: "Save" },
  ),
);
expect(
  await screen.findByText("Settings saved"),
).toBeVisible();

npm test

✓ tests/settings-panel.test.tsx (1 test) 30ms

Ship

Package for Linux

npm run deploy builds the packages from your configuration and generates the desktop entry and AppStream metadata.

Deploying

npm run deploy

  • .flatpakA sandboxed application with a GNOME runtime
  • .debDebian, Ubuntu, and derivatives
  • .rpmFedora and other RPM distributions
  • .AppImageA downloadable executable file

Why GTKX

Node.js owns the process

That is why npm packages, Vite, and Vitest work in a GTKX app. GTKX targets one platform, GTK and Adwaita on Linux, and exposes all of it.

In GJS, GNOME's JavaScript runtime, it is the reverse: your code runs inside GLib's main loop, without Node.js APIs or Node-native tooling.

Node.js event loop your app

  • npm
  • Vite
  • Vitest
  • React

GLib main loop driven by GTKX

  • GTK 4
  • libadwaita
  • the libraries you add
GLib's main loop runs inside Node's, on the main thread.

The tutorial

Build a notes app

Build Notes one feature at a time: Markdown files, a live preview, search in a worker, and link completion. Then test it, translate it, and create installable packages.

All 19 chapters
The Notes window split in two: the sidebar lists five notes with Website relaunch selected, and the content pane, titled Website relaunch, shows its Markdown with highlighted headings, bold text, a link and a numbered list.The Notes window split in two: the sidebar lists five notes with Website relaunch selected, and the content pane, titled Website relaunch, shows its Markdown with highlighted headings, bold text, a link and a numbered list.
GtkSourceView highlights headings, emphasis, and links as you type. Read the chapter