> ## Documentation Index
> Fetch the complete documentation index at: https://webview.js.org/llms.txt
> Use this file to discover all available pages before exploring further.

# WebviewJS on Linux: WebKitGTK, Wayland and X11 Support

> Install WebviewJS on Linux with WebKitGTK. Covers apt, dnf, and pacman setup, X11 and Wayland support, and known Linux-specific limitations.

WebviewJS on Linux uses **WebKitGTK 4.1** — a GTK-integrated port of the WebKit engine. It supports both **X11** (Xlib) and **Wayland** display servers. The active backend is selected automatically at runtime from the available display environment; no configuration flags are required.

## System dependencies

Install the WebKitGTK runtime and development headers for your distribution before installing or building WebviewJS:

<CodeGroup>
  ```bash Debian / Ubuntu theme={null}
  sudo apt install libwebkit2gtk-4.1-dev libxdo-dev
  ```

  ```bash Fedora / RHEL theme={null}
  sudo dnf install webkit2gtk4.1-devel libxdo-devel
  ```

  ```bash Arch Linux theme={null}
  sudo pacman -S webkit2gtk-4.1 xdotool
  ```
</CodeGroup>

After installing the system packages, install WebviewJS normally:

```bash theme={null}
npm install @webviewjs/webview
```

## Supported architectures

| Target triple                   | Architecture | CI       |
| ------------------------------- | ------------ | -------- |
| `x86_64-unknown-linux-gnu`      | x64          | ✅        |
| `aarch64-unknown-linux-gnu`     | arm64        | ✅        |
| `armv7-unknown-linux-gnueabihf` | armv7        | ✅        |
| `i686-unknown-linux-gnu`        | x86 (32-bit) | ⚠️ No CI |

<Info>
  The `i686` (x86 32-bit) target compiles but has no automated CI coverage.
  Test thoroughly before shipping production builds on 32-bit Linux.
</Info>

## Tested environments

| Distribution | Display server  | Status    |
| ------------ | --------------- | --------- |
| Ubuntu 22.04 | X11 / Wayland   | Supported |
| Fedora 40    | Wayland (GNOME) | Supported |
| Arch Linux   | X11 / Wayland   | Supported |
| Debian 12    | X11             | Supported |

## Wayland support

WebviewJS uses Tao's native Wayland backend automatically when a Wayland compositor is present. You can retrieve the native Wayland surface pointer for interoperability with other native libraries:

```js theme={null}
// Returns the wl_surface pointer as a bigint, or 0n when running on X11
const surface = win.getWaylandSurface();

if (surface !== 0n) {
  console.log('Running on Wayland, surface handle:', surface);
} else {
  console.log('Running on X11');
}
```

**Wayland-specific behaviour to keep in mind:**

* Window decorations on Wayland are drawn **client-side** rather than by the compositor.
* Absolute window positioning via `win.setPosition()` **may be ignored** on compositors that enforce the XDG Shell placement protocol (e.g. GNOME Wayland).
* Screen-capture and content-protection APIs are compositor-dependent.

## Known limitations

<Warning>
  **Menu bars are not supported on Linux.** `app.setMenu()` and per-window
  `menu` options compile and run without error, but **`custom-menu-click`
  events are never fired**. Do not rely on menu items for critical application
  actions in Linux builds.
</Warning>

<AccordionGroup>
  <Accordion title="Menu bars">
    `app.setMenu()` and window-level `menu` options run without error, but
    `custom-menu-click` events are **never** emitted on Linux. Do not use menu
    items as the primary interaction surface in Linux builds.
  </Accordion>

  <Accordion title="System tray — pointer events">
    Pointer events (`click`, `mouse-enter`, `mouse-move`, `mouse-leave`) are
    **not emitted** from `TrayIcon` on Linux. Register `click` listeners for
    visual feedback on Windows and macOS only.
  </Accordion>

  <Accordion title="System tray — tooltip and click-menu">
    The `tooltip` field and click-menu configuration on `TrayIcon` are
    unsupported on Linux; these properties are silently ignored. Use a context
    menu opened from within the application window as an alternative.
  </Accordion>

  <Accordion title="setSkipTaskbar">
    `win.setSkipTaskbar(true)` is supported on Linux, but the final behaviour
    depends on the desktop environment and window manager. It may not work as
    expected on all Linux desktop environments.
  </Accordion>
</AccordionGroup>

## Automation

`WebContext` exposes an `allowsAutomation` flag that enables WebDriver-based automated testing:

```js theme={null}
import { WebContext } from '@webviewjs/webview';

const ctx = new WebContext({ allowsAutomation: true });
const win = app.createBrowserWindow();
win.createWebview({ webContext: ctx, url: 'app://localhost/' });
```

<Warning>
  On Linux, WebKitGTK enforces that **only one `WebContext` at a time** can
  have `allowsAutomation: true`. Creating a second automatable context while
  another is active will throw. Use automation contexts for testing only — do
  not enable them in production builds.
</Warning>

## FreeBSD

<Info>
  A `x86_64-unknown-freebsd` target exists in the build matrix, but it has
  **no CI coverage** and the GUI layer is a stub with no real windowing
  implementation. FreeBSD is not suitable for production use of WebviewJS at
  this time.
</Info>