velo

README

velo

A lightweight Go framework for building desktop applications with web frontends.

Velo provides native webview, system tray, file dialogs, and error dialogs across macOS, Windows, and Linux.

Features

• Webview — Native webview window with JavaScript injection and message passing
• System Tray — System tray icon with menus, shortcuts, and click events
• File Dialog — Native file selection dialog
• Error Dialog — Native error dialog

Installation

go get github.com/ltaoo/velo

Building the velo CLI

The velo CLI tool handles building, packaging, and signing your application.

# Install the velo CLI
go install github.com/ltaoo/velo/cmd/velo@latest

# Or build from source
go build -ldflags "-X main.version=1.0.0" ./cmd/velo

Usage

# Build for current platform (in your project directory)
velo build

# Build a specific project
velo build /path/to/project

# Build for a specific platform
velo build -platform darwin
velo build -platform windows
velo build -platform linux
velo build -platform all

# Custom output directory
velo build -out build

# Override version
velo build -version 1.2.3

The velo build command reads app-config.json from the project directory, generates icons, platform configs, and compiles binaries for the target platform(s).

Building the Example Project

cd _example/simple

# Run in development mode
go run .

# Build with the velo CLI (from the example directory)
velo build

# Or build with go directly
go build -o myapp .

The example project uses replace directive in go.mod to reference the local velo module, so no extra setup is needed.

Project Structure

_example/simple/
├── app-config.json    # Application configuration (name, platforms, update, etc.)
├── main.go            # Application entry point
├── frontend/          # Web frontend assets
└── go.mod

app-config.json

The app-config.json file configures your application. Key sections:

• app — Name, version, description, icon
• binary — Output binary name
• platforms — Platform-specific settings (macOS, Windows, Linux)
• build — Build options (config files, excludes)
• release — Release metadata
• update — Auto-update configuration

Example update configuration:

{
  "update": {
    "enabled": true,
    "check_frequency": "startup",
    "channel": "stable",
    "auto_download": false,
    "timeout": 300,
    "sources": [
      {
        "type": "github",
        "priority": 1,
        "enabled": true,
        "need_check_checksum": true,
        "github_repo": "owner/repo"
      },
      {
        "type": "http",
        "priority": 2,
        "enabled": true,
        "manifest_url": "https://example.com/manifest.json"
      }
    ]
  }
}

Quick Start

package main

import "github.com/ltaoo/velo"

func main() {
	box := velo.NewBox()
	box.SetSize(1024, 640)

	box.Get("/api/hello", func(c *velo.BoxContext) interface{} {
		return c.Ok(velo.H{"message": "hello"})
	})

	box.Post("/api/echo", func(c *velo.BoxContext) interface{} {
		return c.Ok(c.Args())
	})

	velo.RunApp("./frontend/dist", box)
}

Subpackages

Package	Description
webview	Native webview window management
tray	System tray icon and menu
file	Native file selection dialog
error	Native error dialog
asset	Embedded JS runtime assets
updater	Auto-update system
buildcfg	Build configuration and code generation

Supported Platforms

• macOS
• Windows
• Linux

License

MIT

Documentation

Overview

Package velo is a lightweight framework for building desktop applications with web frontends. It provides native webview, system tray, file dialogs, and error dialogs across macOS, Windows, and Linux.

Index

• type AppConfig
  • func LoadAppConfig(embedded ...[]byte) *AppConfig
• type Box
  • func NewApp(o *VeloAppOpt) *Box
  • func (b *Box) Get(name string, handler Handler)
  • func (b *Box) NewWebview(opt *VeloWebviewOpt) *webview.Webview
  • func (b *Box) OpenWindow(opt *VeloWebviewOpt) *webview.Webview
  • func (b *Box) Post(name string, handler Handler)
  • func (box *Box) Run()
  • func (b *Box) SendMessage(message interface{}) bool
• type BoxContext
  • func (c *BoxContext) Args() interface{}
  • func (c *BoxContext) BindJSON(obj interface{}) error
  • func (c *BoxContext) Context() context.Context
  • func (c *BoxContext) Deadline() (deadline time.Time, ok bool)
  • func (c *BoxContext) Done() <-chan struct{}
  • func (c *BoxContext) Err() error
  • func (c *BoxContext) Error(message string) string
  • func (c *BoxContext) GetHeader(key string) string
  • func (c *BoxContext) ID() string
  • func (c *BoxContext) Method() string
  • func (c *BoxContext) Ok(data interface{}) string
  • func (c *BoxContext) Query(key string) string
  • func (c *BoxContext) SetContext(ctx context.Context)
  • func (c *BoxContext) SetQuery(query map[string]string)
  • func (c *BoxContext) Value(key interface{}) interface{}
• type BoxResult
• type H
• type Handler
• type Mode
• type VeloAppOpt
• type VeloWebviewOpt

Types

type AppConfig

type AppConfig struct {
	App struct {
		Name        string `json:"name"`
		DisplayName string `json:"display_name"`
	} `json:"app"`
	Update buildcfg.UpdateSection `json:"update"`
}

func LoadAppConfig

func LoadAppConfig(embedded ...[]byte) *AppConfig

type Box

type Box struct {
	Webview *webview.Webview
	// contains filtered or unexported fields
}

func NewApp

func NewApp(o *VeloAppOpt) *Box

func (*Box) Get

func (b *Box) Get(name string, handler Handler)

func (*Box) NewWebview

func (b *Box) NewWebview(opt *VeloWebviewOpt) *webview.Webview

func (*Box) OpenWindow

func (b *Box) OpenWindow(opt *VeloWebviewOpt) *webview.Webview

func (*Box) Post

func (b *Box) Post(name string, handler Handler)

func (*Box) Run

func (box *Box) Run()

func (*Box) SendMessage

func (b *Box) SendMessage(message interface{}) bool

type BoxContext

type BoxContext struct {
	Writer http.ResponseWriter
	// contains filtered or unexported fields
}

func (*BoxContext) Args

func (c *BoxContext) Args() interface{}

func (*BoxContext) BindJSON

func (c *BoxContext) BindJSON(obj interface{}) error

func (*BoxContext) Context

func (c *BoxContext) Context() context.Context

func (*BoxContext) Deadline

func (c *BoxContext) Deadline() (deadline time.Time, ok bool)

func (*BoxContext) Done

func (c *BoxContext) Done() <-chan struct{}

func (*BoxContext) Err

func (c *BoxContext) Err() error

func (*BoxContext) Error

func (c *BoxContext) Error(message string) string

func (*BoxContext) GetHeader

func (c *BoxContext) GetHeader(key string) string

func (*BoxContext) ID

func (c *BoxContext) ID() string

func (*BoxContext) Method

func (c *BoxContext) Method() string

func (*BoxContext) Ok

func (c *BoxContext) Ok(data interface{}) string

func (*BoxContext) Query

func (c *BoxContext) Query(key string) string

func (*BoxContext) SetContext

func (c *BoxContext) SetContext(ctx context.Context)

func (*BoxContext) SetQuery

func (c *BoxContext) SetQuery(query map[string]string)

func (*BoxContext) Value

func (c *BoxContext) Value(key interface{}) interface{}

type BoxResult

type BoxResult struct {
	Code int         `json:"code"`
	Msg  string      `json:"msg"`
	Data interface{} `json:"data"`
}

type H

type H map[string]interface{}

type Handler

type Handler func(c *BoxContext) interface{}

type Mode

type Mode int

const (
	ModeBridge     Mode = iota // webview only, velo:// scheme, no HTTP server
	ModeBridgeHttp             // HTTP server + webview pointing to HTTP
	ModeHttp                   // HTTP server only, no webview
)

type VeloAppOpt

type VeloAppOpt struct {
	Mode                   Mode
	AppName                string
	Title                  string
	IconData               []byte
	QuitOnLastWindowClosed *bool
}

type VeloWebviewOpt

type VeloWebviewOpt struct {
	Pathname    string
	Title       string
	Width       int
	Height      int
	FrontendDir string
	FrontendFS  fs.FS
	EntryPage   string
	OnDragDrop  func(event string, payload string)
	URL         string
}