Wayland client library

low-level wayland client implementation in modern (nodejs 16+) javascript.

No runtime dependencies, no high level abstractions either.

It should be able to manage any wayland protocol extension out there (see the popular ones) through interface definitions parsing.

Installation

npm install wayland-client

If you wish to parse XML protocol files at runtime, you will need to install the xml-js package or provide your own parser.

Protocol files can also be provided pre-compiled as JSON files. See convert.js for an example. This has the added benefit of generating static typings definitions for this protocol.

Usage

Bind a global

import open_display from "wayland-client";
const wl_display = await open_display();
await display.load("protocol/wlr_output_management_unstable_v1.xml");
let wlr_output = await display.bind("zwlr_output_manager_v1");

See the examples folder.

Error handling

Both socket-level errors and fatal Wayland protocol errors are reported on the "error" event of the Display object. Set up a handler after calling init() / open_display():

import open_display from "wayland-client";

const display = await open_display();
display.on("error", (err) => {
  if (err.name === "WaylandProtocolError") {
    // The compositor reported a protocol violation.
    // The connection is already destroyed — do not try to send further requests.
    console.error("Fatal Wayland protocol error:", err.message);
  } else {
    // Low-level socket error (e.g. ECONNRESET).
    // err.code contains the Node.js error code.
    console.error("Socket error:", err.message);
  }
});

WaylandProtocolError is a named export of the package so it can be imported to check err instanceof WaylandProtocolError if needed.

WaylandProtocolError is always fatal — the compositor has destroyed the connection, and calling any further requests will have no effect. No explicit cleanup is needed.

Socket errors (plain Error objects with a .code property) indicate a transport-level failure. Depending on the error code they may or may not be recoverable, but in practice the "close" event will follow shortly after.

Interface-level errors (e.g. an unknown event opcode received for a specific object) bubble up to Display unless the interface itself has an "error" listener:

const surface = await display.bind("wl_surface");
surface.on("error", (err) => {
  // Intercept errors specific to this surface without affecting other objects.
});

This is technically a protocol violation but as it only affects the target object, implementors may choose to handle it locally without crashing the entire connection. It generally happens when the client's interface definition doesn't match the compositor's one.

Use the interface

What happens next depends on the protocol used. The best thing is to make use of the generated types definitions. wayland protocols documentation is also a good resource to get started.

One major use case is to listen to some events until the server is done sending data. To do this, the base Wl_interface class offers an aggregation primitive:

  await display.load(path.join(thisDir, "protocol", "wlr_output_management_unstable_v1.xml"));
  let wlr_output = await display.bind("zwlr_output_manager_v1");
  let {head: heads, done: serial} = await wlr_output.drain(() => once(wlr_output, "done"));

Way better than manually wiring every event recursively. The drain() call collects all events until the "done" event fires, including "done" itself — so serial and heads are both available in the result.

compile a protocol file

npx convert-xml protocol/xdg_shell.xml

Will create a protocol/xdg_shell.json file that can be loaded faster and without the xml-js dependency and a protocol/xdg_shell.d.ts file that will provide types documentation for the xdg_shell interface. Interface names are capitalized in types declaration ( xdg_shell -> Xdg_shell).

Performance

XML protocol parsing is slow. Using pre-compiled JSON files will substantially speed initialization.

The rest of the library uses wayland's wire protocol over a unix socket, so performance should be in line with any other wayland client implementation.

Message reading and writing uses pooled buffers so it shouldn't go too hard on the garbage collector.

Limits

It lacks support for any kind of shared-memory features, mainly because they rely on file descriptor borrowing to share buffers between the client and the backend. It is relatively easy to perform fd borrowing through a native addon but cleanly integrating this (the receiving end in particular) would require reimplementing most of the net.Socket class. A feature request exists for this (#53391) but it's unclear whether it will be implemented one day.

Examples of a good use case might be zwp_idle_inhibit_manager, zwlr_output_manager or managing virtual inputs, like zwlr_virtual_pointer. Some other interfaces that do not require shared memory or file descriptor borrowing should also work fine.

API

Note on types

This module has ts declaration files. The base Wl_interface class has a generic signature of low-level common features. To have robust static typings, it is best to pre-parse protocol files : This will export a json file that cand be loaded with lower overhead and a d.ts file that holds types declarations for this protocol.

Wl_display.bind(...) can then be caracterized with the interface name as a generic parameter.

  let wlr_output = await display.bind<Zwlr_output_manager_v1>("zwlr_output_manager_v1");

This interface inherits from the base Wl_interface class and will have all the methods and events defined from the protocol file, with proper arguments types.

It is of course possible to use the generic Wl_interface primitive without the benefits of typed pre-registered events and methods.

class Wl_display()

async load(interface_name: string)

Load a wayland protocol specification.

Either use a path to a XML file, or a pre-parsed JSON file.

Use pre-compiled JSON files if speed is really important : parsing is ~10x faster than with raw XML.

async bind(interface_name: string)

Binds a global interface. It's the starting point of any interaction with the wayland server.

listGlobals()

List all registered globals on this server. Note that this method is synchronous but one would need to wait for at least one sync event to have happened. Initializing through await wl_display.init() or await open_display() already waits for such an event.

See examples/list_globals.js.

class Wl_interface()

inspect() :string

Outputs a string describing all events and requests provided by this interface.

async drain(until?: (() => Promise<any>) | Promise<any>): Promise<AggregateResult>

Collects all events received by this interface until until resolves, then returns them as a plain object. Defaults to display.sync().

Prefer passing a factory function so the until listener is registered after aggregation begins (no race window):

const result = await itf.drain(() => once(itf, "done"));
// result.done  — args from the "done" event
// result.mode  — args from any "mode" events (array if fired multiple times)

Passing a bare promise also works when the promise is independent of this interface's events.

aggregate(): (() => AggregateResult) & Disposable

Low-level aggregation primitive. Prefer drain() for most use cases.

Returns an end() function that stops aggregation and returns the collected events. The return value also implements Disposable, enabling automatic cleanup with the using keyword:

using end = itf.aggregate();
await once(itf, "done");
const result = end();
// if an exception escapes before end(), using cleans up the listeners anyway

Without using, wrap end() in a try/finally to guarantee cleanup.

Troubleshooting

no socket path provided and XDG_RUNTIME_DIR not set

Wayland requires process.env["XDG_RUNTIME_DIR"] to be set to a valid path.

Generally, it's /run/user/$(id -u)/.

[ERR_MODULE_NOT_FOUND]: Cannot find package 'xml-js'

xml-js is required to import protocol extensions from XML files. Either add it along this package or import only pre-compiled JSON files instead.

Protocol errors

Protocol errors are reported as WaylandProtocolError instances on the Display "error" event. They happen asynchronously and are always fatal — see Error handling for how to distinguish them from socket errors and set up the correct handler.

Ressources

• wayland-book: Wayland Wire protocol manual book
• wayland.xml wayland protocol definition file
• wayland-client wayland C client library implementation

Contributing

Contributions are welcomed.

If you found something that definitely won't work, pelase submit an issue.

Higher-level features should generally be implemented in a separate user-facing package, but I'm open for suggestion if you think some helpers might get used across a wide range of interfaces.

a POC for supporting shared memory and FD borrowing through a native addon would be welcomed.