ToolGUI

This Go package provides a framework for rapidly building interactive data dashboards and web applications. It aims to offer a similar development experience to Streamlit for Python users.

Warning

⚠️ Under Development:

The API for this package is still under development, and may be subject to changes in the future.

Live demo

https://voilelab.github.io/toolgui/demo/ — the demo app covering every component, compiled to WebAssembly and running entirely in your browser, with no server behind it.

Documentation: https://voilelab.github.io/toolgui/, built from docs/. It tracks the latest release; docs/ on dev is ahead of it.

Hello world

package main

import (
	"log"
	"github.com/voilelab/toolgui/toolgui/tgcomp"
	"github.com/voilelab/toolgui/toolgui/tgexec"
	"github.com/voilelab/toolgui/toolgui/tgframe"
)

func Main(p *tgframe.Params) error {
	name := tgcomp.Textbox(p.Sidebar, "What's your name?")
	if name != "" {
		tgcomp.Text(p.Sidebar, "Hi "+name+"~")
	}

	tgcomp.Text(p.Main, "hello ")
	if tgcomp.Button(p.Main, "keep going") {
		tgcomp.Text(p.Main, "world")
	}
	return nil
}

func main() {
	app := tgframe.NewApp()
	app.AddPage("index", "Index", Main)
	e := tgexec.NewWebExecutor(app)
	log.Println("Starting service...")
	e.StartService("127.0.0.1:3000")
}

The app binds to 127.0.0.1 because ToolGUI has no login of its own: whoever reaches the page runs the tool. To serve it to more than this machine, put it behind a proxy that authenticates — see Serving It Safely.

For Dev

Dependency

• Go: version in go.mod
• yarn: Frontend
• cypress: E2E Testing
• taskfile: Task runner
• mdBook: Docs, see docs/README.md

Run demo

task run_demo

cmd/toolgui-todo is a smaller example, a todo list built on the state:

task run_todo

Run tests

task stub_assets
go test ./...
task test_wasm   # tgframe/tgwasm under js/wasm; needs Chrome on PATH

Run E2E Test

task run_demo

cd toolgui-e2e
yarn
yarn e2e:chrome
yarn e2e:firefox

The browser build has its own run, against the wasm demo:

task run_wasm_demo

task test_e2e_wasm

Desktop app

toolgui-wails is a separate Go module that runs the same app in a desktop window with Wails v2. It needs GTK and WebKit, which is why it stays out of the main module. See toolgui-wails/README.md.

task run_wails_hello

Browser app (WebAssembly)

toolgui/tgwasm runs the same app in the browser, compiled to js/wasm, with no server behind it. cmd/toolgui-wasm builds the static site around it, and the component demo is published from it. See toolgui/tgwasm/README.md.

task run_wasm_hello   # the small example
task run_wasm_demo    # the component demo, in the browser

Build without the web assets

toolgui-web/web.go and toolgui-wails/assets.go embed build output that is not committed on dev. To compile Go code without running a frontend build:

task stub_assets
go build ./...

Release

Releases are cut by the Release GitHub Action (Actions → Release → Run workflow), with a vX.Y.Z version as input. It builds the web assets from dev, commits them, tags, and pushes.

go get resolves tags, so the tagged commit is what has to carry toolgui-web/app/build — that is the only reason the built assets live in git at all. main is a CI-owned mirror of the latest release commit; do not commit to it by hand.

Each release moves two tags. toolgui-wails is its own module, and Go resolves a module in a subdirectory through a tag named after that directory, so the workflow also pushes toolgui-wails/vX.Y.Z. Without it go get on the desktop module falls back to dev's head, where the embedded assets are gitignored.