appkit drives the web engine the operating system already ships (WKWebView, WebView2, WebKitGTK) behind one Go API, and layers the desktop services on top: windows, drag regions, native dialogs, notifications, clipboard, tray, single- instance, URL/file opening, and autostart.
Platform libraries are loaded at runtime with purego,
so any target cross-compiles from any host - no MinGW, no sysroots, go install just works.
The package is deliberately small and simple, with no hidden dependencies. The API is designed to be declarative and goroutine-safe. No engine is bundled, so binaries stay small.
# go 1.27.1+
go get github.com/malivvan/webkitgtk@latestappkit binds the OS web engine through purego, so the following platforms are supported by simply setting
GOOS and GOARCH to the desired target and running go build or go install. The engine is chosen automatically
based on the OS.
| GOOS | GOARCH | Engine |
|---|---|---|
| Linux | amd64, arm64*, 386, armv7*, armv6*, armv5*, loong64*, ppc64le*, riscv64*, s390x* | WebKitGTK |
| FreeBSD | amd64, arm64* | WebKitGTK |
| NetBSD | amd64, arm64* | WebKitGTK |
| Windows | amd64, arm64*, 386 | WebView2 |
| Darwin | amd64, arm64* | WKWebView |
Architectures marked with a
*have only been tested to compile, not to run. If somebody has a machine of that architecture and can verify the runtime, please open an issue.
Either
webkit2gtk-4.1
(stable) or
webkitgtk-6.0
(unstable)
is required at runtime. If both are installed the latest version will be used.
| Debian / Ubuntu | apt install libwebkit2gtk-4.1-0 |
apt install libwebkitgtk-6.0-4 |
| RHEL / Fedora | dnf install webkit2gtk4.1 |
dnf install webkitgtk6.0 |
| Alpine | apk add webkit2gtk-4.1 |
apk add webkit2gtk-6.0 |
| Arch | pacman -S webkit2gtk-4.1 |
pacman -S webkitgtk-6.0 |
| Gentoo | emerge -av net-libs/webkit-gtk (slot 4.1 or 6.0) |
|
| NixOS | nix-env -iA nixpkgs.webkitgtk_4_1 |
nix-env -iA nixpkgs.webkitgtk_6_0 |
| FreeBSD | pkg install webkit2-gtk3 (flavor 4.1) |
pkg install webkit2-gtk4 |
| NetBSD | pkg_add webkit-gtk41 |
not yet available (pkgsrc stuck at 2.36.8) |
The environment variable
APPKIT_BACKENDcan be set towebkit2gtk-4.1orwebkitgtk-6.0to force a specific WebKitGTK version.
mkdir hello && cd hello
go mod init hello
go get github.com/malivvan/appkitpackage main
import (
"log"
"github.com/malivvan/appkit"
)
func main() {
app := &appkit.App{Name: "My App", Exit: true}
view := &appkit.View{
Width: 1280, Height: 800,
URL: "app://index.html",
}
if err := app.Show(view); err != nil {
log.Fatal(err)
}
defer view.Close()
if err := app.Wait(); err != nil {
log.Fatal(err)
}
}That is the whole program: a frameless, transparent 1280×800 window whose page is
the chrome. To serve real content, assign an io/fs.FS to App.FS and point the
view at an app:// path (see Core concepts). The goroutine
that shows the first window is pinned to its OS thread, so keep direct window
calls there; run code on the UI thread from elsewhere with
view.Window(func(unsafe.Pointer) { … }), or use the goroutine-safe View
methods (Show, Hide, Maximize, Eval, Emit, …).
To hide the console on Windows: go build -ldflags="-H windowsgui" ..
Declarative windows. Define a View (geometry, options, bindings, first URL)
and hand it to App.Show. An *App is configuration plus a runtime scope, like
http.Server - settings are frozen on the first method call. Wait returns on
App.Quit, or when the last window closes if App.Exit is true.
Secure Context Assign an io/fs.FS to App.FS and every view is served from a
uniform app:// origin - no ports, secure, cross-origin isolated
(COOP/COEP/CORP), so localStorage, crypto.subtle, getUserMedia, and
SharedArrayBuffer all work. HTML files are templates executed with the
requesting View as data (auto-escaped):
<h1>{{.App.Name}}</h1>
<p>{{.URL}} - {{.Width}}x{{.Height}}</p>Bindings App.Bind (app-wide) and View.Bind (per-view) are declarative
maps exposed on the page under window.*. The value's kind alone decides the
behavior - no struct walking or tags:
- Go function → callable; 0 args makes it an awaitable getter, 1 arg a setter
[2]any{getter, setter}→ readable+writable property- Anything JSON-encodable → immutable constant
Names are dotted paths ("api.call" → window.api.call) validated at window
creation. View.Bind overrides App.Bind; all calls return Promises.
Events Every view gets a lightweight pub/sub bridge: view.On / view.Off
/ view.Emit on the Go side, window.events on the page (rename via
App.Events). Each event reaches every listener on both sides exactly once.
Frameless by default Windows are frameless and fully transparent unless
View.Frame is true (which asks for the ordinary OS-framed, opaque window) -
the page is the chrome. Mark movable regions with CSS (-app-region: drag;
Electron's -webkit-app-region alias is accepted), tracked live through
scrolling, resizing, and DOM changes. Double-clicking a drag region toggles
maximize. State controls resizability; StateFixed disables edge resizing.
| Service | API |
|---|---|
| Systray | App.Tray - declarative menu tree, checkboxes, submenus, per-item icons; Linux via D-Bus StatusNotifierItem, so no desktop is excluded |
| Notifications | App.Notify, notify.Show, ShowOpts, Alert, Beep |
| Native dialogs | View.Dialog - open / multi-open / save / directory with filters |
| Clipboard | App.Copy / App.Paste |
| Single instance | App.Exec - later launches forward args and exit; --new-instance bypasses |
| Autostart | App.Autostart() - XDG .desktop, HKCU\…\Run, or macOS LaunchAgent/SMAppService |
| Open / reveal | App.Open / App.Reveal |
| Runtime icon | App.Icon (best-effort; Windows reads from executable resources) |
Only one tray per process (ErrAlreadyRunning on a second).
Show, Hide (hide-to-tray: screen + taskbar), Maximize/Minimize and their
inverses, Focus (caret into the page), Raise, and Maximized (queries the OS
- correct after double-clicking a frameless drag area) are all goroutine-safe.
Geometry is deliberately not mutable at runtime - Wayland and GTK4 disagree
on client-side move/resize, so a unified setter would silently fail. Set the
initial size via View.Width/Height; for later changes, take the native handle
with View.Window and use the platform API.
View.FirstMouse opts into first-click passthrough (clicks reach an unfocused
window). Opt in deliberately - the default protects destructive interfaces from
stray activation clicks. Focus recovers focus when your app knowingly took it
away; prefer it over Raise.
go run ./demo # showcase window (custom chrome, all features)
go run ./demo -frame # the same showcase with the OS window frame
go run ./demo -http # UI over loopback http://localhost (App.HTTP)
go run ./demo -tray # showcase + tray
go run ./demo -selftest # automated self test, exit 0/1go test ./... # unit + GUI smoke tests (GUI tests self-skip headless)
go test -short ./... # headless-only
xvfb-run -a go test ./... # Linux GUI tests under XvfbStandalone subpackage demos: tray/demo, notify/demo, dialog/demo.
make all runs build, vet, tests, the import check, the cross-build matrix, and
the JS-parsing check.
- "none of [libgtk-3.so.0 …] could be loaded" - install a WebKitGTK package
(see Requirements) and confirm it is on the loader path:
ldconfig -p | grep -E 'gtk|webkit'. - Black/blank window on Linux - another GTK stack may be loaded, or you are
missing the matching
libepoxy/GPU driver; tryAPPKIT_BACKENDto pin a stack, or run underxvfb-runto isolate display issues. - No window on a headless box - there is no display; use
xvfb-run -a. - Notifications do nothing on macOS - UserNotifications need a bundled
.appthe user has granted permission;ErrUnavailableis returned otherwise. - WebView2 missing on Windows - install the Evergreen runtime (the app returns a clear error rather than crashing).
See LICENSE.