Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/webviewjs/webview/llms.txt

Use this file to discover all available pages before exploring further.

WebviewJS on Linux renders through WebKitGTK 4.1, a GTK-integrated build of WebKit that ships as a system package on all major distributions. Before running or building WebviewJS you must install both the WebKitGTK library and libxdo, which is used for window-management helpers. The library supports both the X11 and Wayland display servers through Tao, selecting the active backend at runtime based on the environment.

​
Installing Dependencies

Install the required system packages before using WebviewJS on Linux. The package names vary by distribution:
1

Debian / Ubuntu

sudo apt install libwebkit2gtk-4.1-dev libxdo-dev
2

Fedora / RHEL

sudo dnf install webkit2gtk4.1-devel libxdo-devel
3

Arch Linux

sudo pacman -S webkit2gtk-4.1 xdotool
libxdo (xdotool on Arch) provides the X11 window-management utilities that WebviewJS uses internally. It is required even on Wayland sessions.

​
Display Server Support

WebviewJS supports both X11 and Wayland through Tao. The backend is selected automatically at startup from the DISPLAY and WAYLAND_DISPLAY environment variables — no code changes or feature flags are required.

X11

Full window positioning, absolute placement, and system-tray support. The classic, well-tested path.

Wayland

Supported via XDG Shell. Client-side decorations are drawn by adwaita CSD. Some compositor-specific constraints apply.

​
Wayland-Specific Notes

Absolute window positioning via win.setPosition() may be silently ignored on Wayland compositors that enforce the XDG Shell placement protocol. Prefer letting the compositor decide the initial position.
Key differences when running on Wayland:
  • Window decorations are drawn client-side via the adwaita CSD theme.
  • Screen capture and content-protection APIs are compositor-dependent (no universal Wayland equivalent of Win32 SetWindowDisplayAffinity).
  • The Wayland surface pointer is exposed for native interoperability (see below).

​
Getting the Wayland Surface

getWaylandSurface() returns Tao’s native wl_surface pointer as a BigInt, or 0n when the window is running under X11: 
const surface = win.getWaylandSurface();

if (surface !== 0n) {
  console.log('Wayland surface pointer:', surface.toString(16));
} else {
  console.log('Running under X11');
}
Native menu bars use Muda’s GTK integration. WebviewJS retrieves the GTK window and default vertical box directly from Tao, so app.setMenu(), per-window menu options, and CustomMenuClick events all work on Linux: 
import { WebviewApplicationEvent } from '@webviewjs/webview';

app.setMenu({
  items: [
    {
      label: 'File',
      submenu: {
        items: [
          { id: 'new', label: 'New' },
          { id: 'open', label: 'Open' },
          { label: 'Quit', role: 'quit' },
        ],
      },
    },
  ],
});

app.onEvent((event) => {
  if (event.event === WebviewApplicationEvent.CustomMenuClick) {
    console.log('Menu item clicked:', event.customMenuEvent?.id);
  }
});
Menu behaviour is subject to the active GTK theme and desktop environment. Some compositors or minimal WMs may render menus differently from GNOME/KDE defaults.

​
Skip Taskbar

win.setSkipTaskbar(true);
This calls Tao’s GTK implementation. The final behaviour depends on the desktop environment and window manager — GNOME and KDE honour it, but minimal WMs may not.

​
Automation Support

WebContext.setAllowsAutomation() enables WebDriver / automation mode on a WebKit context. This flag is only enforced on Linux and has the constraint that only one context at a time may have automation enabled: 
// Create a context that allows WebDriver automation
const ctx = app.createWebContext({ allowsAutomation: true });

const win = app.createBrowserWindow();
const webview = win.createWebview({}, ctx);
You can also toggle it at runtime: 
ctx.setAllowsAutomation(true);  // enable
ctx.setAllowsAutomation(false); // disable
Only one WebContext may have automation enabled at a time on Linux. Enabling it on a second context while one is already active produces undefined behaviour in WebKitGTK.

​
Tested Environments

DistributionDisplay serverStatus
Ubuntu 22.04X11 / WaylandSupported
Fedora 40Wayland (GNOME)Supported
Arch LinuxX11 / WaylandSupported
Debian 12X11Supported

Build docs developers (and LLMs) love

Get started for freeTalk to us