English | 简体中文

Viva is a Go-first, GPU-native desktop framework. Applications draw through the platform's own window and GPU APIs — Cocoa and Metal, Win32 and Direct3D 11, XCB and Vulkan — with no WebView, no browser engine, and no bundled runtime. It is aimed at small binaries, low idle resource usage, and direct access to native platform capabilities. An application that needs web content can host the system's own web view beside Viva's drawing (WebKitGTK, WKWebView, WebView2): it is opt-in, loaded when the first page opens, and nothing is bundled.

The status list below is what runs today.

Quick start

Viva is a Go module, github.com/vivaui/viva. The viva command builds, packages and live-reloads applications; nothing in it is linked into the program you ship.

brew install vivaui/tap/viva        # macOS, Linux
scoop bucket add vivaui https://github.com/vivaui/homebrew-tap && scoop install viva   # Windows
viva doctor                         # is this machine ready?
viva init hello
cd hello
viva dev .        # hot reload: save a file, the window updates and keeps its state

Prebuilt archives (with SHA256SUMS) are on each release from v0.1.3 on; with Go already installed, go install github.com/vivaui/viva/cmd/viva@latest works too. You do not need Go first: viva build, viva dev and viva init download the official toolchain once into your user cache when there is none (checked against go.dev's SHA-256; VIVA_GO_DOWNLOAD=0 turns it off). A project made by viva init pins the command with a tool line in go.mod, so go tool viva runs the version that project builds against. See the Build and package guide.

viva init writes a runnable project: a window, a test that drives it without opening one, viva.toml, and an AGENTS.md describing the programming model. viva build writes a release program to build/, and viva package writes the platform's own bundle.

Requirements: Go 1.26 or newer (viva fetches it when missing). On macOS the Xcode command-line tools, because Viva reaches Cocoa and Metal through cgo; on Linux, X11 with the system XCB and Vulkan loaders; on Windows, Win32 with Direct3D 11 and DirectWrite. Viva loads the system libraries at runtime and bundles none of them.

The current release is v0.2.3; name it explicitly (@v0.2.3) to pin it. Guides, the API reference, and a component catalog with live previews live in website/; run it with npm run dev there, or read them on vivaui.dev, which is also available in Chinese.

Everything below describes this repository: its measurements, its own programs, and how to work on the framework rather than with it.

Scope

Viva targets native desktop applications on macOS, Windows, and Linux. A WebAssembly/WebGPU backend is optional and must not add cost to native builds. iOS, iPadOS, Android, mobile packaging, and a touch-first mobile runtime are explicitly out of scope. Desktop performance and native integration will not be weakened to preserve hypothetical future mobile compatibility.

All three backends use direct operating-system window and GPU APIs with no WebView and no bundled rendering runtime.

Current Status

• Native macOS window and event loop.
• Direct Metal clear and present.
• Flat generational retained scene with stable node identities.
• Coalesced O(1) localized rectangle updates with zero hot-path allocations.
• Precompiled Metal shader and instanced rectangle rendering.
• Event-driven C-to-Go pointer dispatch and 32-byte partial Metal uploads.
• Paint-order hover and press interaction state with click activation;

• Keyboard focus with Tab traversal, Enter and Space activation, and focus

• Event-driven scrolling with per-primitive clipping: a 1000-row list

• Three native window modes: standard titled, frameless (no traffic lights),

• Explicit multi-window applications through app.RunApplication: every

• Status-area icons and popup panels: Application.AddStatusItem puts an icon

• Application.SetDockBadge puts a label in the red badge macOS draws at the

• app.StoreSecret/LoadSecret/DeleteSecret keep a small secret in the

• ui.MonoFamily draws fixed-pitch text in any installed family and

• Config.OnFileDrop receives files dragged from the file manager, with the hit

• A separate retained semantic accessibility tree mirrored into native

• Event-driven window-resize repainting with exactly one GPU submission per

• Config.OnFrameChange, Config.OnMinimize and Window.Minimized report

• Retained Row/Column/Stack/Flex layout with O(1) unchanged-layout checks.
• Paint-order pointer routing, stable keyboard focus, and Tab traversal.
• Native macOS NSTextInputClient integration with real Chinese IME candidate

• Focus-driven dynamic native text editors on macOS, Windows, and Linux, with

• A separate retained semantic accessibility tree.
• Direct CoreText shaping, system-font fallback, GPU-composited text textures,

• Experimental Windows shell with Win32 events, D3D11 retained rendering,

• Experimental Linux/X11 shell with dynamically loaded system XCB, Vulkan,

• Event-driven rendering with no idle frame loop.
• Theme tokens and a statically typed, source-owned translation of the pinned

• A shared native/WASM component browser: a catalog of every component grouped

• Clean event-loop return on window close or application termination.
• Reproducible binary, startup, CPU, memory, and GPU-submission measurement.

Windows Mica, Mica Alt and Acrylic are enabled through app.Config.WindowBackdrop without changing build commands. Unconfigured windows keep the ordinary renderer. See Windows materials for version limits, fallback behavior and the platforms actually verified.

Native label renderers draw single-line labels. The browser preview runs on the Canvas2D backend.

Run the repository

These commands build and drive the framework's own programs from this checkout.

go run ./cmd/showcase        # the native component showcase
go run ./cmd/component-preview -component button -example variants   # one example, natively
tools/build_web.sh           # viva build --target web, then serves http://127.0.0.1:8090
go run ./tools/docs -check   # the API and component data the website generates from

The browser gallery paints the same Go components through the Canvas2D WebAssembly backend; its visual direction and measured costs are recorded in docs/benchmarks/m3-gallery-style-darwin-arm64.md.

Documentation website

vivaui.dev is the public site, in English and Chinese: guides whose code blocks are files under examples/guides/ that go test builds and drives headlessly, an API reference generated from the Go source, and a page per component with a live Go/WASM preview. The Astro + Svelte source is in website/; it is not part of the native UI or the release runtime.

cd website
npm ci
npm run dev          # http://127.0.0.1:4321/zh/ and /en/
npm test && npm run build

See website/README.md for the preview pipeline, the generated data and test:site.

Build and ship an application

viva build makes a release program for --target darwin, windows, linux or web (-trimpath, stripped, a fixed build ID, so the same sources give the same bytes) and reports its size apart from anything around it. viva package adds the platform's own installer. Both read an optional viva.toml next to go.mod:

[app]
name = "Viva Gallery"       # shown in the menu bar; names the .app
id = "dev.viva.gallery"     # bundle identifier
package = "./cmd/showcase"  # the main package to build
[mac]
min_system = "12.0"         # the macOS the program is compiled for; floor 12.0

go run ./cmd/viva build --target windows --arch amd64
go run ./cmd/viva package --zip
go run ./cmd/viva help package     # every command and flag

viva.toml is decoded strictly: an unknown table or key, a duplicate or a value of the wrong type is an error that names the line. A macOS program is compiled for min_system, not for the macOS of the machine building it, and package refuses a bundle that claims an older system than its program needs. Signing and notarization are opt-in through --sign-identity or APPLE_SIGNING_IDENTITY plus notarytool credentials; --no-sign turns both off. --arch amd64 builds the other Darwin architecture from either host: the build keeps cgo and the Objective-C/Metal bridge and lets clang emit the other Mach-O slice. The Build and package guide covers every target, installer format and flag.

The release link is measured, not assumed. go-toml/v2 is used only by the viva command and purego only by the Linux backend, so neither is in a macOS or Windows program. The development reload protocol, single-instance sockets, PNG icon decoding and the Go test runtime stay out of release programs (reload, single instance and PNG are opt-in packages; the test runtime is absent), and leak counters remain because they cost two atomics per window or driver.

A static canvas can be presented through the public API:

theme := ui.DarkTheme()
var canvas ui.Canvas
components.Card(&canvas, theme, ui.Rect{X: 24, Y: 24, Width: 320, Height: 180})
if err := app.RunCanvas(app.Config{Title: "My App"}, &canvas); err != nil {
    log.Fatal(err)
}

Engineering Rules

The performance budgets, dependency policy, architecture boundaries, and definition of done are enforced by the checked-in benchmarks and tests. Measurements are evidence; terms such as “native speed,” “zero idle work,” and “lightweight” are not used as unverified marketing claims.

Contributing

Bug reports, platform findings, and documentation fixes are always welcome — see CONTRIBUTING.md for the gate a change has to pass and for where the line between framework and application behaviour sits. Security problems go through SECURITY.md, never a public issue.

Contributors

Community

License

Viva is licensed under the Apache License 2.0. See LICENSE and THIRD_PARTY_NOTICES.md.