Skip to main content
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:
After installing the system packages, install WebviewJS normally:

Supported architectures

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

Tested environments

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:
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

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.
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.
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.
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.

Automation

WebContext exposes an allowsAutomation flag that enables WebDriver-based automated testing:
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.

FreeBSD

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.