react-x11

Documentation · Playground — edit react-x11 and watch it render, in your browser, against a JavaScript X server running on the page.

A React renderer for desktop applications, whose host is a display system rather than a document. React's job in a renderer is to compute what changed; the renderer's job is to turn that into side effects on some host — in react-dom those are DOM mutations, here they are X11 protocol requests written to a socket, Core Animation layers and CoreGraphics drawing on macOS, Direct2D drawing on DirectComposition surfaces on Windows, or GL frames handed to a Wayland compositor. There is no DOM and no browser engine underneath: this is not Electron with a different skin, and <div> is not an element that exists. Build GUI programs for a Linux desktop, for a display at the other end of an ssh connection, as a native Mac app or a Windows one, with your React / React Native experience — flexbox layout, components, hooks, synthetic events.

Four backends, one tree

The same components, the same hooks and the same style objects run on all of them. The two that are mature:

• X11 (the flagship) — a Linux desktop, a display forwarded over ssh -X, Xvfb in CI, a thin client, or macOS through XQuartz. Everything is JavaScript all the way down: ntk / node-x11 implement the X11 protocol in pure JS (think xlib rewritten in node.js).
• Cocoa (docs/macos.md) — a real Mac app: NSWindows, the menu bar at the top of the screen, AppKit's own control bezels, native open/save panels, native notifications, Core Animation compositing. No X server anywhere. It rides on @windowkit/appkit, a thin mechanism-only Objective-C++ bridge — an optional dependency shipping prebuilds, absent on Linux installs.

createRoot() picks for you: Cocoa on macOS and win32 on Windows when the matching bridge is installed, X11 via $DISPLAY everywhere else — and X11 on either of those without its bridge, so an XQuartz or WSLg setup keeps working. createRoot({ backend: 'x11' }) or REACT_X11_BACKEND=x11 pins it. On macOS the app's JS runs on a worker while AppKit keeps the main thread, so a menu, a drag or a live resize never stops it — node app.js is enough, and REACT_X11_THREADED=0 keeps the main thread (docs/macos.md).

Two more backends exist beside these, serving the goal of full cross-platform support, and both are younger than the two above. native Wayland (docs/wayland-backend.md) — the wire protocol in JavaScript and a GLES rasterizer of its own, on mutter, sway and labwc, with no Xwayland in the path — is opt-in (REACT_X11_BACKEND=wayland) rather than automatic, because X11 stays the default on Linux: the remote case is the flagship reason this project exists and Wayland has no network transparency. Windows (docs/windows.md) — Win32 windows, Direct2D and DirectWrite, DWM compositing through DirectComposition — is the default on Windows, with the keyboard, an IME, a screen-reader bridge and most of the desktop integrations in place (docs/windows-integrations.md is the measured list). Each is a backend beside the others rather than a replacement for any of them: the same tree, the same components, the same style objects.

Layout is yoga-layout (WASM) on every backend, and text shaping is fontkit through ntk on X11 and Wayland, CoreText on Cocoa and DirectWrite on Windows. npm install never compiles anything: the X11 stack is JavaScript all the way down, and the native addons in the tree — the Cocoa and win32 bridges, and x11-dri for direct GL and the Wayland socket — are optional dependencies that ship prebuilt. And npm test doesn't even need an X server (node-x11 ships an in-process pure-JS X server that the tests render into and read pixels back from; every screenshot below was rendered that way too, by driving the real examples through the real event pipeline).

On X11, the wire carries drawing, not pixels

react-x11 does not rasterize a frame on the client and ship the buffer across. React reconciles the component tree, the renderer turns that diff into drawing operations — rounded rectangles, composited gradients, clip regions, runs of glyph indices — and the X server executes them. The server owns the pixels; the client never had them.

That is what X's RENDER extension is for. Text is shaped once and its glyphs uploaded once, so drawing a line afterwards names them by index, about a byte per glyph; gradients, scaling, alpha compositing and clipping are single server-side requests rather than loops over a pixel array; nothing is read back. An update costs what the drawing costs, not what the window's area costs. Going full-screen on a 4K panel does not multiply your bandwidth, because you were not sending pixels at 1080p either — which is why this stays comfortable on a display forwarded over ssh. Mounting a window with forty rows and their labels is 110 requests and 4.2 KB on the wire, and stalls the pipeline on none of them.

Because that is the design it is measured rather than assumed: npm run bench reports requests, bytes, replies, blocking round trips, RENDER composites and the pixel area those composites touch, against a checked-in baseline (scripts/bench/baseline.json, which is where the numbers in these docs come from).

以上为 README 的开头部分。其余内容请阅读原文。 查看完整 README ↗