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:

• Go >= 1.22
• Bun

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.