Help us shape the future of Go! Take the 2026 Go Developer Survey

bldr

package
v0.57.30 Latest Latest
Warning

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

 Go to latest Published: Oct 29, 2026 License: Apache-2.0 Imports: 22 Imported by: 0

README

Bldr

Introduction

Bldr leverages the Aperture Stack to build modular peer-to-peer applications with real-time user interfaces that run anywhere. Deploys hot-loaded plugins via the p2p network.

The bundler can deploy to many target environments:

  • CLI: client interfaces on the command line.
  • Daemon/Cloud: running as a native Go process.
  • Native: supports Electron and/or OS-provided web views.
  • Firmware: embedded devices (using TinyGo).
  • Mobile: using the gomobile tool.
  • Web Browser: using WebAssembly and WebWorkers.

Uses the Aperture Robotics stack to implement a full peer-to-peer application:

  • ControllerBus: communicating controllers w/ declarative config.
  • Bifrost: p2p communications + pub-sub with pluggable transports.
  • Hydra: storage engine with advanced p2p block-graph structures.
  • Identity and Auth: public-key identity and key derivation.
  • staRPC: bi-directional streaming RPCs between TypeScript and Go.
  • rGraphQL: live-updating streaming GraphQL requests w/ lazy-loading.

Supports advanced data structures (even in the web browser) including:

  • Blob: split a large piece of data into deterministic chunks.
  • File: collection of written Ranges composed of Blobs of data.
  • Git: code revision tracking engine with go-git.
  • Graph: graph database w/ quads: <subject, predicate, object, value>
  • Kvtx: transactional key/value store (i.e. AVL tree).
  • Sql: SQL data store backed by GenjiDB or go-mysql-server.
  • UnixFS: directories, files, permissions, FUSE mounts.
  • World: key/value store coupled with a graph database + changelog.

Each UI and application module is bundled separately and can use any linting, compilation, and frontend approaches.

Overview

Main concepts in the development workflow:

  • Entrypoint: manages executing plugins and starting the initial plugin.
  • Plugin: contains controller factories and a startup ConfigSet.
  • Controller: goroutine managing a portion of the application logic.
  • ConfigSet: list of controllers to start with configuration objects.

The bldr developer tool has the following major command categories:

  • start: starts applications in development mode
  • deploy: pushes plugins to a plugin registry
  • dist: bundles distribution archives (release tarballs)

The bldr developer tool uses Go and esbuild to bundle Go, JavaScript, TypeScript, and other assets into Plugins.

When a Plugin is loaded, its startup ConfigSet is applied, executing any configured startup controllers.

Plugins can communicate with the host and each other via RPC services.

The LoadPlugin directive instructs the plugin host to load a plugin by ID.

CLI

The CLI compiler (bldr/cli/compiler) generates standalone command-line binaries. It scans Go packages for controller factories (NewFactory) and CLI command providers (NewCliCommands), embeds a ConfigSet, and compiles a self-contained binary that boots a DevtoolBus on startup.

See doc/CLI.md for the full guide and example/cli/ for a working example.

Web

The web layer for bldr adds additional concepts:

  • WebDocument: browser page, tab, or Electron BrowserWindow.
  • WebView: location in the WebDocument where Go can load components.
  • WebRuntime: interface to access the Go runtime from JavaScript.

It uses the following browser mechanics:

  • BroadcastChannel: communications channel between two Js components.
  • SharedWorker: parallel background worker shared between all tabs.
  • ServiceWorker: intercepts HTTP requests and forwards to Go runtime.

When running as a native application the Go process is the initial entrypoint to the application, and will start the WebRuntime as a sub-process. For example: extracting & starting the Electron redistributable.

The Web frontend communicates with the Go backend via RPC streams. The frontend and backend can be located in the same browser, as a native process bundled with an Electron app, or separated into client/server.

The ServiceWorker intercepts HTTP requests to the /b/ and /p/ paths. Plugins control the URL space below /p/{plugin-id}/ and can serve any Go HTTP handler at that path, including static assets bundled with the plugin.

Esbuild

The plugin compiler scans Go code for comment directives, ex:

// Entrypoint is the component entrypoint.
//
//bldr:esbuild root.tsx
var Entrypoint bldr_web_bundler.WebBundlerOutput

// Alternatively you can use a string path to the .js entrypoint.
//
//bldr:esbuild root.tsx
var EntrypointURL string

The available comment directives are documented here:

Vite

The plugin compiler can use Vite to bundle the contents of the given entrypoint to the plugin asset filesystem.

// ExampleVitePlugin is the Vite plugin configuration.
//
//bldr:vite vite.config.ts
var ExampleVitePlugin bldr_web_bundler.WebBundlerOutput

All files output from Vite are served starting at the plugin asset path. The root index.html from a Vite build can be accessed by setting this variable.

bldr:asset

// AppFavicon is the favicon .ico asset.
//
//bldr:asset favicon.ico favicon.ico
var AppFavicon string

Recursively copies a file and/or directory to the asset filesystem. Paths are relative to the Go file containing the comment. The resulting URL is stored in the variable associated with the comment.

bldr:asset:href

// AppFaviconHref is the URL to the .ico icon asset.
//
//bldr:asset:href favicon.ico
var AppFaviconHref string

Determines the URL to the given path relative to the assets filesystem root. Conceptually similar to path.Join(assetsFs, givenPath). The resulting URL is stored in the variable associated with the comment.

bldr:esbuild

//bldr:esbuild --any-esbuild-flag component.tsx
var Component bldr_web_bundler.WebBundlerOutput

Uses Esbuild to bundle the contents of the given entrypoint to the plugin asset filesystem. CLI arguments for esbuild are accepted in the comment. Multiple lines with the bldr:esbuild prefix are joined into a single esbuild command. Stores the URL to the root javascript and CSS file in the variable associated with the comment.

An optional flag is the --bundle-id=default flag. All bldr:esbuild directives with the same bundle ID will be combined together into a single esbuild bundle request, with one esbuild entrypoint per bldr:esbuild directive. If you want to have a separate bundle, specify a different --bundle-id=value in the comment.

Flags can also be specified in the plugin compiler config with "esbuildFlags".

Build Tags

bldr will set the following build tags:

  • bldr_analyze: set while analyzing the code for factories
  • build_type_dev: set during development build
  • build_type_release: set during release build

Developing

You need the following tools installed:

Initial setup:

# download deps
bun install

Here are some of the available ways to start bldr from the spacewave repo root:

# start web application with GoScript browser Go plugins (loads web plugin via --plugins)
bun run bldr:start:web

# start web application with standard Go/WASM browser Go plugins
bun run bldr:start:web:wasm

# explicit alias for the default GoScript mode
bun run bldr:start:web:goscript

# start native application (loads web plugin via --plugins)
bun run bldr:start:desktop

# start CLI application (loads bldr-demo-cli plugin via --plugins)
bun run bldr:start:cli

# build web (wasm) distribution bundle & serve
bun run bldr:start:web:release

# build release bundle for all platforms
bun run bldr:build:release:cross

Terminal Status and Logs

bldr start and bldr build show a live terminal dashboard when stdin and stderr are terminals. The dashboard projects the command state, manifest fetch and build progress, plugin health, controller activity, and recent errors from the devtool status model. Press Ctrl-C to cancel the command; press o from a web start dashboard to open the browser. Use --no-tui or BLDR_NO_TUI=1 to keep plain terminal output.

Diagnostic logs are written to a timestamped file under .bldr/logs/ while the dashboard owns the terminal. Concurrent bldr start, bldr build, and bldr publish commands against the same --state-path serialize on .bldr/state.lock. When a second command would collide with an active state owner, Bldr prints the holder PID and state root before waiting for the lock. Use separate --state-path values only when CI or local proofs need independent web and desktop state trees to run in parallel.

Start Plugins

The bldr start command accepts a --plugins flag to load additional plugins on startup. These are merged with any plugins declared in bldr.yaml under start.plugins.

# load specific plugins for the start session
bldr start --plugins web native
bldr start --plugins bldr-demo-cli native
bldr start --plugins web --plugins extra-plugin web

The start.plugins list in bldr.yaml declares plugins that are always loaded. The --plugins flag adds to this list without modifying the config file, allowing different start configurations for different targets (native, web, CLI).

Environment Variables

  • BLDR_FROM_SOURCE=1: Forces building saucer from vendored C++ sources instead of resolving a prebuilt binary from the @aptre/bldr-saucer npm package. Useful when developing saucer itself or when prebuilt binaries are not available for your platform.
export BLDR_FROM_SOURCE=1
bun run bldr:start:desktop

Chromium SharedWorker Debugging

In Chromium: to view the SharedWorker developer tools:

  • Open chrome://inspect
  • Select "Shared workers"
  • Click "inspect" on the SharedWorker

Testing

Run unit tests:

bun run bldr:test

Run browser E2E tests (requires a web release build):

# Build the web release bundle first
bun run bldr:build:release:web

# Run E2E tests in headless Chromium
bun run bldr:test:e2e

The E2E tests use Vitest browser mode with Playwright to test the full web release build, including service worker registration, SharedWorker initialization, and WASM runtime loading.

VSCode Debugging

To debug the Electron main process:

  • Press Command + Shift + P
  • Select "Debug: Attach to Node Process"
  • Select the Electron instance.

To debug the Electron renderer process:

  • Copy bldr/.bldr/src/.vscode/launch.json to .vscode/launch.json
  • Select "Run and Debug" in the left bar.
  • Click the green play button for "Debug Electron Renderer Process"

This is only enabled in Debug builds for Electron, where the plugin compiler will automatically configure the web plugin to start Electron with --inspect=5858 for the main process.

This is enabled by the plugin compiler for Electron in debug builds only.

Documentation

Index

Constants

View Source 
const DistGoMod = "github.com/s4wave/spacewave/bldr-dist"

DistGoMod is the Go module path used for the checked-out Bldr dist sources.

Variables

View Source 
var DistSources embed.FS

DistSources contains the sources for the web entrypoint(s) and sdk(s). Includes entrypoints, runtime workers, shared package import bindings, and SDK modules. These files must be checked out to .bldr/src so TypeScript + IDEs can see them.

TODO: go.mod go.sum bun.lock tsconfig.json ?

Functions

func BuildDistSourcesFSCursor 

func BuildDistSourcesFSCursor() *unixfs_iofs.FSCursor

BuildDistSourcesFSCursor builds a *fs.Cursor for the DistSources.

func BuildDistSourcesFSHandle 

func BuildDistSourcesFSHandle(ctx context.Context, le *logrus.Entry) *unixfs.FSHandle

BuildDistSourcesFSHandle builds a unixfs FSHandle for the DistSources.

func PrepareTypeScriptProject 

func PrepareTypeScriptProject(ctx context.Context, le *logrus.Entry, sourceRoot, distRoot string, sources map[string]fs.FS) error

PrepareTypeScriptProject materializes the shipped compiler and SDK source closure. Bldr's dependency cache prepares both SDK and declared project dependencies before any compiler starts. The source and dist directories are owned checkouts.

func SyncDistSources added in v0.51.7 

func SyncDistSources(ctx context.Context, le *logrus.Entry, conf DistSourceSyncConfig) error

SyncDistSources syncs embedded Bldr dist sources into DistRoot and materializes the vendor tree used by non-local @go/* TypeScript imports.

Types

type DistSourceSyncConfig added in v0.51.7 

type DistSourceSyncConfig struct {
	// RepoRoot is the project root containing the live go.mod and go.sum.
	RepoRoot string
	// DistRoot is the output directory used as BLDR_DIST_ROOT.
	DistRoot string
	// BldrVersion is the module version to require when BldrSrcPath is empty.
	BldrVersion string
	// BldrSum is the module checksum for BldrVersion.
	BldrSum string
	// BldrSrcPath is an optional replacement path for the source module.
	BldrSrcPath string
}

DistSourceSyncConfig configures Bldr dist-source materialization.

Source Files

View all Source files

Directories

Path Synopsis
cli
compiler
entrypoint
cmd
bldr command
devtool
desktop
control
tray
update
callpath
Package callpath finds static call paths between Go functions.
 Package callpath finds static call paths between Go functions.
status
trace
trace/parser
trace/parser/raw
Package raw provides an interface to interpret and emit Go execution traces.
 Package raw provides an interface to interpret and emit Go execution traces.
trace/parser/tracev2
Package tracev2 contains definitions for the v2 execution trace wire format.
 Package tracev2 contains definitions for the v2 execution trace wire format.
trace/parser/version
web
web/entrypoint command
web/entrypoint/controller
compiler
compiler/bundle
entrypoint
Package distpath resolves Bldr dist source paths.
 Package distpath resolves Bldr dist source paths.
e2e
comms
comms/fixtures/go/goscript-opfs-storage
comms/fixtures/go/goscript-resource-service
downstreamapp
entrypoint
compose
Package compose carries the project-supplied part of a host process.
 Package compose carries the project-supplied part of a host process.
fatal
Package fatal carries process-fatal boot conditions from bus controllers to the entrypoint command that owns the process exit.
 Package fatal carries process-fatal boot conditions from bus controllers to the entrypoint command that owns the process exit.
state
Package state defines the durable state shared by native entrypoints.
 Package state defines the durable state shared by native entrypoints.
storagepath
cli
Package example_cli provides example CLI commands for the bldr demo.
 Package example_cli provides example CLI commands for the bldr demo.
exp
autobun/main command
build
builder
builder/controller
builder/resultworld
fetch
fetch/plugin
fetch/rpc
fetch/world
materializer
pack
world
go
npm
assets/http
compiler
compiler/esbuild
Package esbuild builds JavaScript plugins from a source filesystem and integrity-pinned npm tarballs, without a package manager or disk checkout.
 Package esbuild builds JavaScript plugins from a source filesystem and integrity-pinned npm tarballs, without a package manager or disk checkout.
compiler/go
compiler/go/dev-wrapper command
compiler/js
entrypoint
entrypoint/controller
forward-lookup-block
forward-rpc-service
handle-web-view
host
host/configset
host/controller
host/default
host/export
host/logs
Package plugin_host_logs contains structured plugin log schema types.
 Package plugin_host_logs contains structured plugin log schema types.
host/mock
Package plugin_host_mock provides plugin host test doubles.
 Package plugin_host_mock provides plugin host test doubles.
host/process
host/resource
host/root
host/scheduler
host/static
Package plugin_host_static resolves LookupPluginHost with a fixed set of plugin hosts that another component runs.
 Package plugin_host_static resolves LookupPluginHost with a fixed set of plugin hosts that another component runs.
host/storage
host/storage/volume
host/wazero-quickjs
host/wazero-quickjs/gen command
host/web
load
pluginid
vardef
vardef/ast
bunlock
Package bunlock reads integrity-pinned npm dependencies from bun.lock and stores verified tarballs in a caller's block-backed dependency tree.
 Package bunlock reads integrity-pinned npm dependencies from bun.lock and stores verified tarballs in a caller's block-backed dependency tree.
controller
starlark
validate
watcher
prototypes
build-web-pkg command
detect-parent-exit command
go-js-async-iterable command
go-js-packet-stream command
http-reader-at command
http-reader-at/make-example-kvfile command
js-wazero-quickjs command
js-wazero-quickjs/concio command
js-wazero-quickjs/nonblockio command
js-wazero-quickjs/repl command
simple/app
sync-optimization command
test-gomod-compare: Tests whether comparing the generated go.mod with the existing file on disk can be used to skip go mod tidy + vendor.
 test-gomod-compare: Tests whether comparing the generated go.mod with the existing file on disk can be used to skip go mod tidy + vendor.
wasi command
wasi/run-wazero-go command
webworker-rpcstream/app1
webworker-rpcstream/app2
webworker-rpcstream/common
client
proxy
Package resource_proxy serves a client's Resource SDK from a resource tree of its own, mapped onto an upstream tree whose connection can be replaced.
 Package resource_proxy serves a client's Resource SDK from a resource tree of its own, mapped onto an upstream tree whose connection can be replaced.
server
state
sdk
plugin/host
Package statepath owns cleanup policy for Bldr state roots.
 Package statepath owns cleanup policy for Bldr state roots.
browser
cli
controller
default
inmem
native
node
Package storage_node binds Node SQLite connections to the existing volume factory.
 Package storage_node binds Node SQLite connections to the existing volume factory.
volume
world
tui
host
util
buildbudget
Package bldr_buildbudget bounds concurrent memory-heavy Bldr build stages.
 Package bldr_buildbudget bounds concurrent memory-heavy Bldr build stages.
buildcache
Package bldr_util_buildcache stores the outputs of deterministic build steps, keyed by the step's request and validated by the content of every file the step read, so a rebuild that reads the same content replays the outputs instead of running the step.
 Package bldr_util_buildcache stores the outputs of deterministic build steps, keyed by the step's request and validated by the content of every file the step read, so a rebuild that reads the same content replays the outputs instead of running the step.
bus-bridge
compress
cstate
exec
filehash
framedstream
gocompiler
hostmem
Package hostmem reports the physical memory of the host.
 Package hostmem reports the physical memory of the host.
iofs
logfile
Package logfile provides file-based logging for bldr via logrus hooks.
 Package logfile provides file-based logging for bldr via logrus hooks.
logline
Package logline provides an io.Writer that logs each line a child process writes at the logrus level the line names.
 Package logline provides an io.Writer that logs each line a child process writes at the logrus level the line names.
merge
node
npm
opt/wasm
packedmsg
pipesock
qjsbytecode
Package bldr_util_qjsbytecode caches ES modules compiled to bytecode by the QuickJS-NG WASI reactor, so a later QuickJS instance links a module without parsing its source.
 Package bldr_util_qjsbytecode caches ES modules compiled to bytecode by the QuickJS-NG WASI reactor, so a later QuickJS instance links a module without parsing its source.
reliteral
singleton-muxed-conn
tailwriter
Package tailwriter provides an io.Writer that forwards all writes to an inner writer while keeping the last N complete lines in a ring buffer.
 Package tailwriter provides an io.Writer that forwards all writes to an inner writer while keeping the last N complete lines in a ring buffer.
termui
valuelist
wazerofs
Package wazerofs provides a simplified filesystem adapter that bridges UnixFS with the Wazero WebAssembly runtime's filesystem interface.
 Package wazerofs provides a simplified filesystem adapter that bridges UnixFS with the Wazero WebAssembly runtime's filesystem interface.
Package bldr_values contains value types that are injected to the target binary.
 Package bldr_values contains value types that are injected to the target binary.
web
boot
bundler
bundler/esbuild
bundler/esbuild/build
bundler/esbuild/compiler
bundler/rolldown
bundler/vite
bundler/vite/compiler
document
document/controller
electron/desktop-runtime
entrypoint/browser
entrypoint/browser/build
entrypoint/browser/bundle
entrypoint/browser/message-port
entrypoint/electron/bundle
entrypoint/index
entrypoint/saucer/bundle
entrypoint/startuptrace
Package startuptrace installs the opt-in browser runtime startup trace.
 Package startuptrace installs the opt-in browser runtime startup trace.
fetch
fetch/service
pkg
pkg/compiler
pkg/controller
pkg/esbuild
pkg/esbuild/determine-cjs-exports
pkg/external
pkg/fs
pkg/fs/controller
pkg/http
pkg/mock
pkg/rpc
pkg/rpc/client
pkg/rpc/e2e
pkg/rpc/server
pkg/static
pkg/vite
plugin
plugin/browser
plugin/browser/build
plugin/browser/controller
plugin/compiler
plugin/controller
plugin/electron
plugin/handle-rpc
plugin/handle-web-pkg-assets
plugin/handle-web-pkg-rpc
plugin/handle-web-view-rpc
plugin/saucer
runtime
runtime/bootstrap
runtime/controller
runtime/goscript/build
runtime/http
Package web_runtime_http serves the Bldr /b/ routes from a bus.
 Package web_runtime_http serves the Bldr /b/ routes from a bus.
runtime/sw
runtime/wasm
runtime/wasm/build
view
view/client
view/handler
view/handler/controller
view/handler/server
view/observer
view/server
worker

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.