node-x11 ships an X server in JavaScript and runs its own protocol tables
sidorares/node-x11 is an open-source project for practical engineering and operations.
At a glance
- What is it?
- A Node client implementing the core X11 protocol plus fifteen extensions, with no runtime dependencies. It runs in a browser against a bundled pure-JavaScript X server, treats the display string as a pluggable transport, and generates its protocol code from the specification rather than typing it by hand.
- Who is it for?
- node-x11 suits anyone who needs to speak to a real display server from JavaScript without shelling out to a native library, since the absence of runtime dependencies means the install risk is nil and the portability surface is unusually wide. It suits you less if you want widgets, because this is a protocol client and the higher-level toolkit is a separate project.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 6 days ago.
- What is it written in?
- Mainly JavaScript, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.
Star history
- sidorares/node-x11543 ★ · +14
| Repository | 2026-08-01 | 2026-11-15 |
|---|---|---|
| sidorares/node-x11 | 529 | 543 |
14 Stars in the last 106 days, measured from the daily GitHub snapshot. Compare with other projects
Editorial analysis
Fifteen extensions and not one runtime dependency
The package describes itself as a pure JavaScript client implementing the X Window protocol and its extensions, and the dependency list is empty at runtime.
Everything in the development dependency set is for testing, linting or code generation. There is no native module to compile and no native module to break on a new Node release, which for a project of this age is the main practical achievement.
The extension coverage is broad enough to be the reason to choose it over the alternatives: rendering, damage tracking, compositing, big requests, display power management, screen saver control, fixes, shape, the test extension, miscellaneous client information, GLX, and three of the modern direct-rendering pieces. On top of that sits a vendor-specific extension for one desktop environment's window management hints.
That last group is what makes the direct-rendering path possible: GPU frames travel as kernel buffers through the modern rendering path rather than being copied through the wire protocol, which is what you need for anything approaching interactive performance.
The minimum runtime is Node 18. Two maintainers are named in the manifest.
Installation is a single package install:
npm install x11The extension list is the reason the package is large: this is protocol coverage, not a helper library. Core requests are issued directly against a client handle, and window creation is spelled out rather than hidden behind a widget abstraction:
const x11 = require('x11');
x11.createClient((err, display) => {
const X = display.client;
const root = display.screen[0].root;
const wid = X.AllocID();
X.CreateWindow(wid, root, 0, 0, 500, 500, 0, 0, 0, 0, {});
X.MapWindow(wid);
});There is no widget layer here. Anything above this line is a separate library built on the protocol.
It bundles an X server written in JavaScript
The most unusual thing about this project is not the client, it is the server.
A pure-JavaScript X server ships inside the package. The live playground on the documentation site runs ordinary node-x11 code in your browser against that server, including OpenGL, which is bridged by running GLX over WebGL.
That turns an entire class of dependency into a dev dependency. You can develop against the display server the package carries instead of installing one, which is why the browser demo can exist at all: there is no X server on the machine running the browser, so the package had to bring its own.
There is a separate test target dedicated to that server, which suggests it is maintained as a first-class component rather than a demo convenience.
It is worth being clear about the boundary, though. A JavaScript server implemented to run a browser playground is not the same thing as a mature system X server, so behaviour observed there is a good sign the client works and a poor guide to what you will hit in production.
The repository's own notes gesture at this gap, listing other server-side implementations for JavaScript as prior art while describing a fully web-based playground as something that would be great to build.
The display string is a transport, not just a hostname
Normally a display string tells a client where to connect: a protocol, a host and a screen number. Here it can also tell the client how.
Display strings accept a pluggable protocol prefix. You register a protocol name together with a connect function, and then reference it in the display string with that name followed by a host and screen. A separate factory accepts any duplex stream directly.
So the client is not hard-wired to a Unix socket or a TCP port. If you have a stream, you have a display.
That single design decision is what makes the browser case work at all, since a browser has no Unix socket and the transport there is something else entirely. It also means the client can be pointed at a proxy or a tunnel without touching the protocol code.
There is a dedicated guide on custom transports, which suggests the extension is meant to be used rather than merely advertised.
The dependency list being empty matters here too: a client with no native networking dependency can be pointed at whatever stream the host environment happens to provide, because it never had to bind a port itself.
On Windows the requirement is stated plainly: install an X server implementation first, since there is nothing built in.
Under Bun, file descriptors arrive as well as depart
Two runtimes are supported and the second one has a capability the first lacks.
The package runs under Bun, and the documentation is explicit about which parts work: the ones that pass file descriptors over the connection. Shared memory segments and direct-rendering buffers are both in that category, and both are things a client cannot synthesise.
The claim is that under Bun descriptors can also be received, not only sent, and it is described as unique to that runtime.
That is a small detail with real consequences. A one-way handle is enough to share memory you allocated. To receive one means the server can hand you a buffer it owns, which is a different shape of protocol and the kind of thing that only works when the underlying runtime exposes it.
There is a dedicated test target that runs the Bun test suite, which is how that claim stays true across runtime upgrades.
Everything else here is about portability of the client rather than features: the same code, the same protocol, more environments it can run in. That is the recurring theme of the project, and it is why the browser and Bun support get first-class documentation and their own test scripts.
Protocol tables are generated from the specification
The repository contains an autogen directory and two scripts that regenerate parts of the client.
One generates events and the other generates replies, and a third runs both in sequence. That is the whole implementation strategy for the protocol surface: the tables come out of the specification rather than being typed in by hand and drifting.
For a protocol with this many requests and replies, hand-maintaining the tables is the obvious way to accumulate bugs, so generating them is the difference between a library that tracks the specification and one that is stuck at whatever release someone implemented.
Two development dependencies support the wider testing story. One is a mock HTTP server implementation, which lets protocol conversations be asserted without a display server in the loop. The other is a test framework often used for exactly this kind of request and reply scripting.
The published package points at the library directory as its entry point, and ships the sources alongside the built code.
Release automation is also visible: a configuration file and a manifest for an automated release tool, which explains why the version history shows several releases inside a single week. The default branch is named for the older convention rather than the newer one.
Six test targets, including an emulated graphics stack
Testing is split into six named targets rather than one, and the names reveal what is actually being validated.
The default test script runs a custom runner. A local variant delegates to a shell script. Then there are four environment-specific suites: one for an emulated GL stack, one for the bundled X server, one for Bun, and linting.
The emulated GL target exists because real hardware GL is not available on a build machine, which is the same reason the browser playground bridges GLX over WebGL.
Splitting by environment is the right call for a library whose whole claim is that it runs in several of them. A single test run on one runtime would not tell you anything about the others, and the four suites mean a regression in, say, the Bun path is caught rather than discovered by a user.
The example directory matches that structure. Alongside the obvious demonstrations for painting, screenshots, OpenGL, direct rendering, a keyboard heatmap, key recognition, a PDF viewer, a VNC viewer, a window manager and a game, there are folders for several graphics formats, a smoke test, and a folder for an X virtual framebuffer.
The userland projects built on top of the library span the same range, from higher-level toolkits to tiling window managers, a PDF viewer, a VNC client, a Unity global menu client, and a JavaScript version of a famously small teaching window manager.
Editorial conclusion
node-x11 suits anyone who needs to speak to a real display server from JavaScript without shelling out to a native library, since the absence of runtime dependencies means the install risk is nil and the portability surface is unusually wide. It suits you less if you want widgets, because this is a protocol client and the higher-level toolkit is a separate project. Before depending on it, decide whether you are writing for a real X server or for the bundled one, because the bundled server is what makes the browser playground possible but is not what production behaviour looks like, and pin Node 18 or newer as the floor.
Frequently asked questions
What X11 extensions does node-x11 implement?
The core protocol plus rendering, damage, compositing, big requests, display power management, screen saver control, fixes, shape, the test extension, miscellaneous client information, GLX, and the modern direct-rendering pieces including DRI3 and Present, plus a vendor window-management extension.
Does node-x11 work in a browser?
Yes. The package ships a pure-JavaScript X server that the documentation playground runs against in your browser, including OpenGL through GLX over WebGL. Display strings accept a pluggable protocol prefix and a client factory accepts any duplex stream.
What are the runtime dependencies of node-x11?
None. Every dependency is a development dependency used for testing, linting or code generation, so there is no native module to compile. The minimum supported runtime is Node 18 or newer.
Does node-x11 run under Bun?
Yes, including the parts that pass file descriptors over the connection, such as shared memory segments and direct-rendering buffers. Under Bun those descriptors can also be received, which the documentation describes as unique to that runtime.
How is the protocol code maintained?
It is generated rather than hand-written. Two scripts regenerate events and replies from the specification, and a third runs both, so the request and reply tables track the specification instead of drifting from it.
What do I need before installing node-x11 on Windows?
An X server implementation, such as XMing or the Cygwin distribution of X, installed first. Nothing is built in on Windows, so the client has something to connect to.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/sidorares-node-x11)Star history chart for your README
[](https://hysenlabs.com/projects/sidorares-node-x11)Was this useful?