lightron

package module
v0.4.11 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 13, 2026 License: MIT Imports: 21 Imported by: 0

README

Lightron

Desktop apps in Go and web pages, on the Chromium the computer already has.
A 3 MB download instead of Electron's 100 MB.

Go Reference CI MIT

lightron.Run(lightron.Options{
	Name:    "Notes",
	ID:      "com.example.notes",
	Icon:    icon,
	Handler: http.FileServer(http.FS(pages)), // or URL: "http://localhost:8080"
	Bind: map[string]any{
		"save": func(name, text string) error { return os.WriteFile(name, []byte(text), 0o644) },
	},
})
await lightron.invoke("save", "todo.md", text);

Why

An Electron app ships a whole Chromium: every app 100–200 MB to download, and as much again on disk. Yet nearly every Mac has Chrome (or Edge, Brave), and every Windows 10/11 machine has WebView2. Lightron runs your app on that one.

What you ship is a Go program. Measured on the hello example:

Download On disk
macOS (arm64) .dmg 3.0 MB 6.5 MB
Windows (x64) installer 2.3 MB 7.0 MB

And unlike opening a browser window from Go (lorca and the like), the app is an app: on macOS, its own name and icon in the Dock and ⌘Tab, its own menu bar, its own notifications; windows with a bare title bar, not a browser's tabs and address bar.

How

  • macOS: the user's own Chrome, or Edge, Brave, Chromium. Lightron makes a copy of the browser's bundle in the app's data directory (an APFS clone: a second, and no disk space), renamed into your app (name, bundle id, icon), and runs that, so macOS sees your app, not Chrome. It drives the browser over the DevTools protocol, on a pipe. Windows are --app windows. A small library loaded into the browser edits its menu bar into yours and handles the Dock.
  • Windows: WebView2, the system's Chromium (Edge's engine, updated with Windows), in a window of the app's own.

Both are current Chromium: the same web platform as Chrome, the DevTools you know, no polyfills.

docs/architecture.md explains each part and why it is done that way.

Getting started

Go 1.23 or later.

go install github.com/zbysir/lightron/cmd/lightron@latest
lightron init notes        # main.go, web/index.html, icon.png, lightron.json
cd notes && go run .

Package it:

lightron build             # dist/Notes-0.1.0-darwin-arm64.dmg, …-windows-amd64-setup.exe, .zip of each

lightron build cross-compiles: from a Mac you get the macOS and Windows packages (the Windows installer needs makensis: brew install makensis). lightron doctor says what this machine has.

The page's side

Every page of the app gets window.lightron:

await lightron.invoke("name", ...args) // call a function in Options.Bind; rejects with its error
lightron.send(value)                   // to Options.OnMessage
lightron.on("event", (data) => {})     // from app.Emit / window.Emit; returns an unsubscribe function
lightron.focus()                       // bring this window (and the app) forward, e.g. from a notification's onclick
lightron.getPathForFile(file)          // a dropped / pasted / picked File's path on disk ("" if it has none);
                                       // also in an app's page in another site's iframe
lightron.platform                      // "darwin" | "windows"

Links to other sites (<a href> and window.open) open in the default browser; links to the app's other origins (Options.Origins) that ask for a new window open one of the app's. A window can also navigate to another site (an app that shows a web app, say): window.lightron and Bind are only ever on the app's own origins. Notifications and the clipboard are allowed without asking.

The Go side

lightron.Run(lightron.Options{
	Name, ID, Version string
	Icon     []byte                 // square PNG, 512px+
	URL      string                 // a page served by something else…
	URLFunc  func() (string, error) // …or one known only once it's started (your backend)…
	Handler  http.Handler           // …or pages served by Lightron, on a private loopback port
	Window   lightron.WindowOptions // Path, Width, Height
	Menu     []lightron.MenuItem    // macOS menu bar (nil: a standard one)
	DockMenu []lightron.MenuItem
	Bind     map[string]any         // functions for lightron.invoke
	Script   string                 // JS for every page, after window.lightron (a compatibility layer)
	PageScript string               // JS for every page of any site a window shows (no bridge there)
	Origins  []string               // more origins that are the app's ("http://*.localhost:7000")
	BrowserArgs []string            // extra engine switches
	UserAgentSuffix string          // " MyApp/1.2" after the browser's User-Agent
	Protocols []string              // URL schemes ("notes" for notes://…), to OnURL
	OnURL     func(*lightron.App, string)
	OnMessage, OnReady, OnSecondInstance …
	KeepRunning bool                // stay in the Dock with no window
})

OnReady hands you the *App: NewWindow(path), Emit(event, data), SetBadge("3"), SetMenu(menu), Quit(), and per window Eval, Emit, Focus, Close. For what Lightron has no API for, App.Call and Window.Call send DevTools protocol commands. Only one instance runs; opening it again brings a window up. Every option, method and platform difference: docs/api.md. Also pkg.go.dev and examples/.

Updates: the update package checks a feed (lightron feed writes it; a GitHub release works as the host), downloads the new package, and installs it once the app quits. See docs/updates.md.

Compared with

Lightron Electron Wails Tauri
Engine system Chromium (Chrome / WebView2) bundled Chromium system webview system webview
macOS engine Chromium Chromium WebKit (Safari) WebKit (Safari)
App size ~3 MB 100 MB+ ~8 MB ~5 MB
Backend Go Node.js Go Rust
Build needs Go (no cgo) Node Go + cgo, platform SDKs Rust, platform SDKs
Linux not yet ✓ ✓ ✓
Native APIs small (menus, Dock, windows) huge medium large, plugins

Pick Lightron when you want Chromium on every platform without shipping it, a Go backend, and builds that are plain go build. Pick Electron for its ecosystem and APIs, or when your app must not depend on what is installed. Pick Wails or Tauri when Safari's engine on macOS is fine and you need Linux.

Caveats

Know these before you choose it:

  • macOS needs a Chromium browser installed: Chrome, Edge, Brave or Chromium. Most Macs have one; without one the app says so and offers Chrome's download page (lightron.ErrNoBrowser).
  • The first start after a browser update is slow: macOS checks the freshly made copy, 10–30 s with a "Verifying" dialog. It happens once per browser version.
  • macOS 11+, Windows 10/11 (WebView2 comes with Windows 11 and current Windows 10; otherwise the app opens its download page). Linux isn't supported yet.
  • Windows: one window per app for now; the menu bar options are macOS's (KeepRunning puts an icon in the notification area instead).
  • Signing: lightron build signs ad hoc. For distribution outside your own machines, sign with your Developer ID and notarize the .app (macOS), sign the installer (Windows). The browser copy is made and signed on the user's Mac, so it never needs your signature.
  • The browser is the user's: Lightron doesn't ship or modify Chrome; it runs a local copy of what the user installed, with its own profile. It inherits that browser's updates (good) and its policies (managed machines may restrict flags).

Status

Lightron is the desktop shell of Gerdr (a GUI for coding agents), which moved off Electron onto it, made into a library. The API may still change before 1.0; changes are listed in CHANGELOG.md.

License

MIT

Documentation

Overview

Package lightron makes desktop apps out of web pages, on a Chromium that is already on the machine instead of one shipped with every app (Electron's ~100MB). A Go program calls Run with the page to show; what users install is that program, a few MB.

  • macOS: the user's own Chrome (or Edge, Brave, Chromium), run from a copy of its bundle renamed into the app (its name, id and icon), so the Dock, ⌘Tab, the menu bar and notifications are the app's. Windows are --app windows: a bare title bar. Lightron drives it over the DevTools protocol (a pipe, not a port).
  • Windows: WebView2, the system's Chromium (Edge's), in a window of the app's own.

The page talks to Go through window.lightron (see bridge.js): invoke a bound Go function, send a message, listen to events. Links to other sites open in the default browser. See README.md and docs/ for how it works and why.

Index

Constants

This section is empty.

Variables

View Source
var ErrNoBrowser = ErrUnsupported

ErrNoBrowser is macOS's; declared here so code using it builds everywhere.

View Source
var ErrUnsupported = errors.New("lightron: this platform isn't supported yet")

ErrUnsupported is returned by Run on a platform Lightron doesn't run on yet (Linux), and by what a platform doesn't have (Window.Call on Windows).

View Source
var Separator = MenuItem{Separator: true}

Separator is a menu separator line.

Functions

func Accelerator

func Accelerator(acc string) (key string, mods []string)

Accelerator parses an accelerator ("Cmd+Shift+K", "Ctrl+Enter", "F5") into a key equivalent and its modifiers (cmd, ctrl, shift, alt), the way AppKit menus take them. An empty string gives "".

func Run

func Run(opts Options) error

Run shows the app and blocks until it quits. Call it from main.

Types

type App

type App struct {
	// contains filtered or unexported fields
}

App is a running app.

func (*App) Call added in v0.2.0

func (a *App) Call(method string, params any) (json.RawMessage, error)

Call sends a DevTools protocol command to the browser (not to a page; see Window.Call) and returns its result: what Lightron has no API for. On Windows (one window, no browser-level session) it goes to the window's page. Lightron relies on the targets it attached to; don't detach from them or turn off domains it enabled (Runtime, Page, Inspector).

func (*App) Emit

func (a *App) Emit(event string, data any)

Emit sends an event to every window (see Window.Emit).

func (*App) FocusOrOpen

func (a *App) FocusOrOpen()

FocusOrOpen brings a window up, or opens one if there is none.

func (*App) NewWindow

func (a *App) NewWindow(path string) error

NewWindow opens a window on path ("" = the page's root), or on a full http(s) URL (any page, e.g. one of Options.Origins). Not on Windows yet: it returns an error there while the window is open.

func (*App) Quit

func (a *App) Quit()

Quit closes the windows and makes Run return.

func (*App) SetBadge

func (a *App) SetBadge(label string)

SetBadge shows label on the app's Dock icon ("" clears it). macOS only.

func (*App) SetDockMenu added in v0.2.0

func (a *App) SetDockMenu(menu []MenuItem)

SetDockMenu replaces the Dock icon's menu (Options.DockMenu).

func (*App) SetMenu added in v0.2.0

func (a *App) SetMenu(menu []MenuItem)

SetMenu replaces the macOS menu bar (Options.Menu): another language, the label of an update that is ready, keys the person changed. nil: the default menu.

func (*App) Windows

func (a *App) Windows() []*Window

Windows are the open windows.

type MenuItem struct {
	Label string
	// Accelerator is shown next to the item and triggers it when the page doesn't take the key: "Cmd+Shift+K",
	// "Cmd+,", "Ctrl+Enter", "F5".
	Accelerator string
	// Role makes it a standard item (Label and Click may be empty): hide, hideOthers, unhide, quit, undo, redo, cut,
	// copy, paste, selectAll, minimize, zoom, front, close, toggleFullScreen, zoomIn, zoomOut, resetZoom, devTools,
	// reload; and, at the top level of Menu, editMenu and windowMenu.
	Role string
	// Click runs when the item is chosen, with the focused window (nil if none).
	Click func(w *Window)
	// Submenu makes it a menu.
	Submenu []MenuItem
	// Separator makes it a separator line.
	Separator bool
}

MenuItem is a menu item, a separator, or a submenu.

func DefaultMenu

func DefaultMenu(name string) []MenuItem

DefaultMenu is the menu bar an app gets when Options.Menu is nil: the app menu (Hide, Hide Others, Show All, Quit), Edit and Window. Start from it to add your own:

menu := lightron.DefaultMenu("Notes")
menu = append(menu[:2], append([]lightron.MenuItem{{Label: "File", Submenu: …}}, menu[2:]...)...)

type Options

type Options struct {
	// Name is the app's name in the Dock / taskbar, ⌘Tab, the menu bar and notifications.
	Name string
	// ID is a reverse-DNS identifier (com.example.notes): macOS bundle ids, data directories.
	ID string
	// Version is the app's version (shown nowhere by Lightron; for your About box and updates).
	Version string
	// Icon is a square PNG, 512px or larger. On macOS it becomes the app's icon in the Dock.
	Icon []byte

	// URL is a page served by something else, e.g. a backend your app starts. An http URL on this machine is shown
	// at http://<Host>/ (see Host); https and remote URLs are shown as they are.
	URL string
	// URLFunc returns URL instead, once Lightron knows this is the only instance running (a second one only hands
	// over to the first and returns): for an app that starts its backend first and shows what that serves. An error
	// ends Run.
	URLFunc func() (string, error)
	// Handler serves the pages instead: Lightron runs it on a private loopback port that only the app's windows can
	// use (a secret cookie, set on the first load).
	Handler http.Handler
	// Splash is a page (HTML) the first window shows while URLFunc runs, so the app answers at once while its backend
	// starts; the window then goes to the app's pages. A plain page: no bridge, nothing it loads from elsewhere is
	// guaranteed (inline its styles). Only with Host "-" (otherwise ignored: URLFunc runs first, as without).
	Splash string
	// Host is the name pages are shown at (http://<Host>/), when the page is http on this machine. The browser writes
	// the page's origin under every web notification ("notes" reads better there than "127.0.0.1:53817"), and keeps
	// the page's storage (localStorage, IndexedDB) by origin: a fixed name keeps it when the port changes. Default:
	// the last part of ID, lowercased.
	// "-": pages stay at their real address (a backend that checks the Host header).
	Host string

	// Window is the first window. Path is relative to the page's root ("/" by default).
	Window WindowOptions

	// Menu is the macOS menu bar: its first item's Submenu is the app menu, the others are menus in order. Items
	// with Role "editMenu" / "windowMenu" stand for the browser's own Edit and Window menus (they handle copy /
	// paste, the window list). nil: an app menu (Hide, Quit…), Edit, Window.
	Menu []MenuItem
	// DockMenu is the menu of the app's Dock icon on macOS (above the window list and Quit macOS adds).
	DockMenu []MenuItem

	// Bind are Go functions the page can call: await lightron.invoke("name", ...args). Arguments arrive as JSON
	// decoded into the parameters' types; return a value, an error, or (value, error). A first parameter of type
	// *Window receives the window that called.
	Bind map[string]any
	// Script is JavaScript run in every page of the app before the page's own scripts, after window.lightron is set
	// up: a compatibility layer for an existing web app (window.yourNative = …), settings to seed.
	Script string
	// PageScript is JavaScript run in every page a window shows, of any site, before the page's own scripts (on
	// Windows also in every iframe: check window.top === window for the page itself): for an
	// app whose windows also show other sites (it can add to them, e.g. a panel of the app's own in an iframe).
	// window.lightron is there only on the app's own pages (the origin of URL / URLFunc / Handler, and Origins):
	// other sites never get the bridge, nor do Script or Bind reach them.
	PageScript string
	// Origins are more origins whose pages are the app's (bridge, Script, Bind), besides the one it starts at:
	// "http://127.0.0.1:7000", or "http://*.localhost:7000" for any subdomain.
	Origins []string
	// BrowserArgs are extra command-line switches for the engine (macOS) / WebView2 (Windows), e.g.
	// "--disable-features=…". They apply to the app's own profile only.
	BrowserArgs []string
	// UserAgentSuffix is appended to the browser's User-Agent, in every window (" MyApp/1.2"), so sites can tell
	// they are inside the app.
	UserAgentSuffix string
	// OnMessage receives what the page sends with lightron.send(value).
	OnMessage func(w *Window, msg json.RawMessage)
	// OnReady runs once the first window has been asked for.
	OnReady func(a *App)
	// OnSecondInstance runs when the app is opened again while running (only one runs at a time). Default: bring a
	// window up, or open one.
	OnSecondInstance func(a *App)

	// Protocols are URL schemes the app opens ("notes" for notes://…): a link of one, clicked in a browser or another
	// app, starts the app if needed and goes to OnURL. macOS: the engine claims them (its Info.plist, made default
	// handler) when the app first runs; Windows: registered for the current user at each start (and by the installer
	// when lightron.json lists them).
	Protocols []string
	// OnURL receives each link of Protocols the app is opened with: at start (it may come before the first window has
	// loaded), or while running (instead of OnSecondInstance). The link is as it came: check it before acting on it,
	// any web page can send one.
	OnURL func(a *App, url string)

	// KeepRunning keeps the app running when its last window closes (macOS: the Dock icon reopens one). Default:
	// quit.
	KeepRunning bool
	// DataDir holds Lightron's state (the browser profile, the engine copy on macOS). Default:
	// ~/Library/Application Support/<ID>/lightron, %LOCALAPPDATA%\<ID>\lightron.
	DataDir string
	// Logf receives Lightron's log lines. Default: log.Printf.
	Logf func(format string, args ...any)
}

Options describe the app. Name, ID, and one of URL, URLFunc or Handler are required.

type Window

type Window struct {
	// contains filtered or unexported fields
}

Window is one window of the app.

func (*Window) Call added in v0.2.0

func (w *Window) Call(method string, params any) (json.RawMessage, error)

Call sends a DevTools protocol command to this window's page (Runtime.evaluate, Page.navigate, SystemInfo-style queries…) and returns its result. On Windows through WebView2's CallDevToolsProtocolMethod. See App.Call.

func (*Window) Close

func (w *Window) Close()

Close closes the window.

func (*Window) Emit

func (w *Window) Emit(event string, data any) error

Emit calls the page's lightron.on(event, …) listeners with data (any JSON value).

func (*Window) Eval

func (w *Window) Eval(js string) error

Eval runs JS in the window's page.

func (*Window) Focus

func (w *Window) Focus()

Focus brings the window and the app to the front.

func (*Window) ID

func (w *Window) ID() string

ID is the window's identifier, stable while it is open.

type WindowOptions

type WindowOptions struct {
	Path          string
	Width, Height int // default 1200 × 800
}

WindowOptions describe a window.

Directories

Path Synopsis
cmd
lightron command
Command lightron starts, packages and publishes Lightron apps.
Command lightron starts, packages and publishes Lightron apps.
examples
hello command
hello: a Lightron app whose pages are served by a Go http.Handler, calling Go from JS and back.
hello: a Lightron app whose pages are served by a Go http.Handler, calling Go from JS and back.
wrap command
wrap: an app around a page served by something else, e.g.
wrap: an app around a page served by something else, e.g.
internal
cdp
Package cdp is a minimal Chrome DevTools Protocol client over --remote-debugging-pipe: JSON messages, each followed by a NUL byte, the browser reading fd 3 and writing fd 4.
Package cdp is a minimal Chrome DevTools Protocol client over --remote-debugging-pipe: JSON messages, each followed by a NUL byte, the browser reading fd 3 and writing fd 4.
macengine
Package macengine finds the Chromium-family browser on a Mac and makes the copy of it an app runs on: the app's name, id and icon in its Info.plist, so to macOS the running browser is the app (its Dock icon, ⌘Tab entry, menu bar, notifications), and its --app windows have a bare title bar.
Package macengine finds the Chromium-family browser on a Mac and makes the copy of it an app runs on: the app's name, id and icon in its Info.plist, so to macOS the running browser is the app (its Dock icon, ⌘Tab entry, menu bar, notifications), and its --app windows have a bare title bar.
macmenu
Package macmenu holds the macOS menu library (objc/menu.m, built into lightronmenu.dylib by `make menulib`) and writes it out for the engine to load.
Package macmenu holds the macOS menu library (objc/menu.m, built into lightronmenu.dylib by `make menulib`) and writes it out for the engine to load.
pack
Package pack writes what packaging needs without the platform's tools: icons (.icns, .ico), Info.plist, the NSIS installer script.
Package pack writes what packaging needs without the platform's tools: icons (.icns, .ico), Info.plist, the NSIS installer script.
Package update keeps a Lightron app up to date from a feed: a JSON file listing the latest version and a package per platform (what `lightron feed` writes), e.g.
Package update keeps a Lightron app up to date from a feed: a JSON file listing the latest version and a package per platform (what `lightron feed` writes), e.g.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL