Vugu: Building Browser UIs in Pure Go with WebAssembly

A Vue-Inspired Component Model in Go

Vugu's core proposition is straightforward: write your browser UI in Go, compile it to WebAssembly, and run it in the browser without any JavaScript tooling. The README describes it as 'a VueJS-inspired library in Go targeting wasm'.

The component format uses `.vugu` files. The generator `vugugen` processes these files and produces Go source. Components can include CSS, respond to DOM events, use `vg-if` and `vg-for` for conditional and iterative rendering, set dynamic attributes with `:prop='expr'` syntax, and communicate through Go-only component events. The README lists slots and server-side rendering as implemented features.

The alternative comparison point is GopherJS, an older project that compiles Go to JavaScript rather than WebAssembly. GopherJS targets JavaScript compatibility at the cost of a larger output; Vugu targets WebAssembly directly. TinyGo compilation is also supported according to the roadmap, which allows smaller binary output at the cost of some Go standard library compatibility.

Prerequisites Before Running Vugu

Vugu imposes a specific set of prerequisites. The Go version requirement is stated explicitly in the README:

git clone https://github.com/magefile/mage
cd mage
go run bootstrap.go

This installs `mage`, the build tool Vugu uses instead of Make. The README states that Go v1.22.3 is the minimum because it depends on the for-loop variable changes introduced in that version.

Beyond mage, contributors and example runners need Docker installed. Each example runs inside a local nginx container. The `goimports` tool is also required:

go install golang.org/x/tools/cmd/goimports@latest

For end users building their own applications rather than running the examples, Docker is not needed for the application itself, but the README focuses on the contributor workflow when it comes to setup instructions.

Running the Examples: What Each Command Does

All examples live under the `examples/` directory. Each subdirectory is its own Go module. To build and serve all examples at once:

mage examples

This spins up nginx containers and serves each example at a URL based on its directory name:

http://localhost:8888/fetch-and-display

To run a single example:

mage singleExample github.com/vugu/vugu/example/fetch-and-display

The examples available include `fetch-and-display`, `html-form`, `dom-events`, `vg-for`, `vg-if`, `simple`, `embed-and-translate`, and `compound-component`. These cover the main primitives of the component model.

The verbose flag shows build output:

mage -v examples

Creating a New Example: The Required Steps

The README documents the new-example workflow in detail, which is useful for understanding Vugu's internal structure. The process starts by copying an existing example:

cp -r ./examples/fetch-and-display/ ./examples/my-new-example

Critically, the `.gitignore` file must be present in the copy to prevent Vugu-generated files from being committed. Then the `go.mod` module name must be updated to match the new example name. Finally, two paths in `index.html` must be updated: the `wasm_exec.js` script path and the `main.wasm` binary fetch URL.

The files `main_wasm.go` and `wasm_exec.js` should not be edited. These are the WebAssembly bootstrap files. The editable entry points are `root.vugu` and `root.go`.

This workflow illustrates a structural constraint: each Vugu application manages its own WebAssembly bootstrap. There is no shared runtime distributed separately.

Library Architecture and the Experimental Label

The README distinguishes Vugu from frameworks with a specific phrase: 'it's built more like a library than a framework'. Frameworks call your code; Vugu expects your code to call it. The render loop, application wiring, and initialization all remain under the developer's control. Vugu generates some scaffolding for new projects, but does not impose its own application lifecycle.

This is an honest description of the current state. The README roadmap marks most features as complete, including DOM events, modification tracking, URL routing, TinyGo support, and SSR. A component library is listed as work in progress.

The experimental label in the repository description is not decorative. The README uses it three times. The project has had no GitHub releases, and the documentation is hosted at vugu.org rather than in the repository itself. Server-side rendering works but is described as needing more documentation.

The generated tools include `vugugen` (compiles `.vugu` files to Go source), `vugufmt` (formats `.vugu` files), and `vgfrom` (scaffolding). The repository module path `github.com/vugu/vugu` depends on `vugu/html`, `vugu/vjson`, and `vugu/xxhash`, all from the same project family. The `js/` directory in the repository contains the JavaScript bridge code that connects the Go WebAssembly runtime to the browser DOM. This bridge is a thin layer; the bulk of the rendering logic is in Go.

The repository also includes a `vgform/` package for form-related utilities, a `staticrender/` package that supports the static HTML output feature listed in the roadmap, and a `v2/` directory which represents an in-progress version increment. A CONTRIBUTING.md file documents the contribution workflow. The `golang.org/x/text` dependency in go.mod handles Unicode text processing across locales, which matters when component state includes non-ASCII content.

License and Maintenance

Vugu is released under the MIT license. The last push to the repository was on 2026-09-23.

The build system switched from Travis CI to mage in May 2024 according to the Updates section of the README. The go.mod requires Go 1.22.3, confirming the minimum version stated in the README.

The module path is `github.com/vugu/vugu`, and the dependency list includes `chromedp` for testing, `vjson` and `vhtml` from the Vugu project family, and `xxhash` for change tracking. There are no JavaScript dependencies. The `wasm_exec.js` file is part of the Go standard library toolchain, not an npm package.

Editorial conclusion

Vugu suits Go developers who want to prototype browser UIs without adopting JavaScript tooling, or who are exploring what a Go-native front-end stack looks like in practice. It is explicitly experimental and the README flags several areas still in progress. Teams building production applications that need a stable, supported UI framework should treat Vugu as a research project rather than a deployment dependency. Check the Go version requirement before starting: the library requires Go 1.22.3 or later due to for-loop changes introduced in that version.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. Project website
4. README
5. vugu/vugu on GitHub