Electrobun

https://framework.blackboard.sh/electrobun/
Admin
Electrobun is a cross-platform framework for building fast, lightweight desktop applications with...
Tokens:79,357
Snippets:880
Trust Score:5.5
Update:1 month ago
Show doc for...
Tokens:
Raw
### Run the application

Source: https://framework.blackboard.sh/electrobun/guides/hello-world-bun

Install dependencies, sync the project, and start the development server.

```bash
hutch install
hutch electrobun sync
hutch run dev
```

--------------------------------

### Install Hutch and Initialize Project

Source: https://framework.blackboard.sh/electrobun/guides/what-is-electrobun

Use the shell script to install the Hutch CLI and initialize a new Electrobun project.

```bash
curl -fsSL https://hutch.blackboard.sh/hutch/install.sh | sh
hutch electrobun init
```

--------------------------------

### Initialize a New Zig Project

Source: https://framework.blackboard.sh/electrobun/guides/hello-world-zig

Create a new project from a template to get started quickly.

```bash
hutch electrobun init my-app --template=zig-wgpu
```

--------------------------------

### Run the application

Source: https://framework.blackboard.sh/electrobun/guides/quick-start

Commands to navigate to the project directory and start the development server.

```bash
cd my-app
hutch run dev
```

--------------------------------

### Execute build and install commands

Source: https://framework.blackboard.sh/electrobun/guides/bundling-and-distribution

Commands to trigger the installation and build processes for specific release channels.

```bash
hutch run install
hutch run build:canary
hutch run build:stable
```

--------------------------------

### Build and Install Electrobun Applications

Source: https://framework.blackboard.sh/electrobun/guides/cross-platform-development

Execute these commands on each native runner to install dependencies and build the stable release.

```bash
hutch run install
hutch electrobun build --env=stable
```

--------------------------------

### Run Development Environment

Source: https://framework.blackboard.sh/electrobun/guides/creating-ui

Command to start the application in development mode.

```bash
hutch run dev
```

--------------------------------

### Install Linux Runtime Dependencies

Source: https://framework.blackboard.sh/electrobun/guides/cross-platform-development

Install required system libraries for Electrobun's Linux native wrapper based on the distribution.

```bash
# Ubuntu or Debian
sudo apt install libgtk-3-0 libwebkit2gtk-4.1-0 libayatana-appindicator3-1 librsvg2-2


# Fedora or RHEL
sudo dnf install gtk3 webkit2gtk4.1 libappindicator-gtk3 librsvg2


# Arch or Manjaro
sudo pacman -S gtk3 webkit2gtk-4.1 libayatana-appindicator librsvg
```

--------------------------------

### Initialize Project via Package Runner

Source: https://framework.blackboard.sh/electrobun/guides/what-is-electrobun

Initialize a project using npm or bun if the Hutch CLI is not already installed globally.

```bash
npx electrobun init
# or
bunx electrobun init
```

--------------------------------

### Prepare Electrobun Environment

Source: https://framework.blackboard.sh/electrobun/apis/cli/cli-args

Resolves the release, installs the platform core, and refreshes the SDK projection without building the application.

```bash
hutch electrobun prepare
hutch electrobun prepare --env=stable
```

--------------------------------

### Execute package manager commands via Hutch CLI

Source: https://framework.blackboard.sh/electrobun/apis/cli/cli-args

Examples of using the hutch pm interface to install dependencies and execute binaries when an external package manager is configured.

```bash
hutch install
hutch pm ci
hutch pm install zod
hutch pm exec -- tsc --version
```

--------------------------------

### createUIWindow

Source: https://framework.blackboard.sh/electrobun/apis/ui/overview

Creates a GpuWindow, mounts the UI tree, and starts the frame tick.

```APIDOC
## createUIWindow(options, app)

### Description
Creates a GpuWindow, mounts the UI tree, and starts the frame tick. The app callback builds the UI with the element API.

### Parameters
- **options** (object) - Required - Configuration object containing title, width, height, titleBarStyle, transparent, alwaysOnTop, background, and tickMs.
- **app** (function) - Required - Callback to build the UI.

### Returns
- **window** (GpuWindow) - The underlying GpuWindow instance.
- **context** (UiContext) - The mount's UiContext.
- **dispose** (function) - Function to tear down the reactive scope and close the window.
```

--------------------------------

### Install Hutch CLI

Source: https://framework.blackboard.sh/electrobun/guides/quick-start

Commands to install the Hutch CLI on different operating systems.

```bash
curl -fsSL https://hutch.blackboard.sh/hutch/install.sh | sh
```

```powershell
& ([scriptblock]::Create((irm https://hutch.blackboard.sh/hutch/install.ps1)))
```

--------------------------------

### Configure hutch.config.ts

Source: https://framework.blackboard.sh/electrobun/guides/quick-start

Example configuration file defining the Electrobun version and task scripts.

```typescript
export default {
  electrobun: {
    version: "2.0.0",
  },
  scripts: {
    install: ["hutch", "install", "--frozen-lockfile"],
    dev: ["hutch", "electrobun", "dev", "--watch"],
  },
};
```

--------------------------------

### Install Hutch on macOS or Linux

Source: https://framework.blackboard.sh/electrobun/guides/hutch

Use this command to install the current production channel of Hutch on Unix-based systems.

```bash
curl -fsSL https://hutch.blackboard.sh/hutch/install.sh | sh
```

--------------------------------

### Initialize Project with HMR Template

Source: https://framework.blackboard.sh/electrobun/guides/hot-reloading

Creates a new Electrobun project using a specific Vite template and starts the HMR development environment.

```bash
hutch electrobun init my-app --template=react-tailwind-vite
cd my-app
hutch run dev:hmr
```

--------------------------------

### Hutch Configuration Syntax

Source: https://framework.blackboard.sh/electrobun/guides/hutch

Example of a hutch.config.ts file defining project scripts and optional version overrides.

```javascript
export default {
  // Optional exact override:
  // electrobun: { version: "2.0.1-beta.0" },
  scripts: {
    install: ["hutch", "install", "--frozen-lockfile"],
    ui: ["hutch", "pm", "exec", "--", "vite", "build"],
    dev: ["hutch", "electrobun", "dev", "--watch"],
    build: ["hutch", "electrobun", "build", "--env=stable"],
  },
};
```

--------------------------------

### Configure Bytecode in ElectrobunConfig

Source: https://framework.blackboard.sh/electrobun/apis/cli/build-configuration

Example of setting the bytecode option within the Electrobun configuration file to optimize startup performance.

```typescript
import type { ElectrobunConfig } from "electrobun";


export default {
  app: {
    name: "My App",
    identifier: "com.example.my-app",
    version: "1.0.0",
  },
  build: {
    mainProcess: "cottontail",
    cottontail: {
      entrypoint: "src/bun/index.ts",
      // Faster startup, source still shipped and debuggable:
      bytecode: true,
      // Or protect your source (accept the trade-offs below):
      // bytecode: "obfuscate",
    },
  },
} satisfies ElectrobunConfig;
```

--------------------------------

### hutch electrobun init

Source: https://framework.blackboard.sh/electrobun/apis/cli/cli-args

Initializes a new Electrobun project from the template catalog. Supports interactive mode or direct template selection with channel and installation configuration.

```APIDOC
## hutch electrobun init

### Description
Creates a new project from the Electrobun template catalog. Can be run interactively or with flags to specify the project name, template, and release channel.

### Usage
hutch electrobun init [project-name] [--template=name] [--channel=stable|beta|production|canary] [--beta] [--skip-install]

### Parameters
- **project-name** (string) - Optional - The name of the directory to create for the new project.
- **--template** (string) - Optional - The name of the template to use from the catalog.
- **--channel** (string) - Optional - Specifies the release channel (stable, beta, production, or canary).
- **--beta** (flag) - Optional - Shorthand to select the beta template catalog.
- **--skip-install** (flag) - Optional - Skips the execution of the template's defined install task.
```

--------------------------------

### Define Electrobun Build Configuration

Source: https://framework.blackboard.sh/electrobun/apis/cli/build-configuration

Example configuration object defining application metadata and platform-specific build settings for macOS, Windows, and Linux.

```typescript
import type { ElectrobunConfig } from "electrobun";


export default {
  app: {
    name: "Cross Platform App",
    identifier: "com.example.cross-platform",
    version: "1.0.0",
  },
  build: {
    mac: {
      bundleCEF: true,
      bundleWGPU: true,
      defaultRenderer: "cef",
      codesign: true,
      notarize: true,
      icons: "App.icon",
    },
    win: {
      bundleCEF: true,
      bundleWGPU: true,
      defaultRenderer: "cef",
      autoGrantPermissions: ["camera", "microphone"],
      icon: "assets/icon.ico",
    },
    linux: {
      bundleCEF: true,
      bundleWGPU: true,
      defaultRenderer: "cef",
      icon: "assets/icon.png",
      flatpak: {
        enabled: true,
        runtimeVersion: "25.08",
      },
    },
  },
} satisfies ElectrobunConfig;
```

--------------------------------

### Stable Installer Artifact Names

Source: https://framework.blackboard.sh/electrobun/guides/bundling-and-distribution

Examples of stable installer filenames which omit channel prefixes and canary suffixes.

```text
macos-arm64-MyCoolApp.dmg
win-x64-MyCoolApp-Setup.zip
linux-x64-MyCoolApp-Setup.tar.gz
```

--------------------------------

### Initialize project directory

Source: https://framework.blackboard.sh/electrobun/guides/hello-world-go

Create and enter the project directory.

```bash
mkdir hello-go
cd hello-go
```

--------------------------------

### Initialize Project Directory

Source: https://framework.blackboard.sh/electrobun/guides/hello-world-odin

Create the project directory and navigate into it.

```bash
mkdir odin-hello
cd odin-hello
```

--------------------------------

### Initialize Electrobun Project

Source: https://framework.blackboard.sh/electrobun

Use the Hutch CLI to scaffold a new Electrobun project.

```bash
hutch electrobun init
```

--------------------------------

### Initialize an Odin Project

Source: https://framework.blackboard.sh/electrobun/guides/hello-world-odin

Bootstrap a new project using a specific template via the hutch CLI.

```bash
hutch electrobun init odin-app --template=odin-particles-wgpu
```

--------------------------------

### Verify Hutch Installation

Source: https://framework.blackboard.sh/electrobun/guides/quick-start

Check that the Hutch CLI is correctly installed and available in the system path.

```shell
hutch --version
```

--------------------------------

### Install Hutch on Windows PowerShell

Source: https://framework.blackboard.sh/electrobun/guides/hutch

Use this command to install Hutch on Windows systems via PowerShell.

```powershell
& ([scriptblock]::Create((irm https://hutch.blackboard.sh/hutch/install.ps1)))
```

--------------------------------

### Initialize project directory

Source: https://framework.blackboard.sh/electrobun/guides/hello-world-bun

Create and enter a new directory for the application.

```bash
mkdir my-app
cd my-app
```

--------------------------------

### Create a Window and Webview in Go

Source: https://framework.blackboard.sh/electrobun/apis/browser-window

Initializes window and webview options using the electrobun package and creates them through the core.

```go
windowOptions := electrobun.NewWindowOptions(
    "My app",
    electrobun.NewRect(160, 100, 960, 640),
)
windowOptions.Callbacks = electrobun.WindowCallbacks{
    Close: func(uint32) { _ = core.StopEventLoop() },
}
windowID, err := core.CreateWindow(windowOptions)


webviewOptions := electrobun.NewWebviewOptions(
    windowID,
    "views://mainview/index.html",
    electrobun.NewRect(0, 0, 960, 640),
)
webviewID, err := core.CreateWebview(webviewOptions)
```

--------------------------------

### Implement Main Process in Odin

Source: https://framework.blackboard.sh/electrobun/guides/hello-world-odin

Create the main entry point in src/odin/main.odin to initialize the Electrobun core and launch the UI.

```odin
package main


import "core:fmt"
import "core:thread"
import "core:time"


import electrobun "electrobun_sdk:electrobun"


DEFAULT_SECRET_KEY :: "1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23,24,25,26,27,28,29,30,31,32"


g_core: ^electrobun.Core
g_bundle_paths: ^electrobun.BundlePaths


create_ui :: proc() {
  time.sleep(150 * time.Millisecond)


  if err := electrobun.configureWebviewRuntimeFromExecutableDir(g_core, g_bundle_paths, 0);
     err != .None {
    fmt.eprintfln("[hello] failed to configure webview runtime: %v", err)
    return
  }


  window_options := electrobun.defaultWindowOptions("Hello Electrobun")
  window_options.frame = {x = 160, y = 100, width = 800, height = 600}
  window_id, window_err := electrobun.createWindow(g_core, window_options)
  if window_err != .None {
    fmt.eprintfln("[hello] failed to create window: %v", window_err)
    return
  }


  webview_options := electrobun.defaultWebviewOptions(window_id)
  webview_options.url = "views://mainview/index.html"
  webview_options.frame = {x = 0, y = 0, width = 800, height = 600}
  webview_options.secret_key = DEFAULT_SECRET_KEY
  webview_options.sandbox = false
  webview_options.callbacks = {
    decide_navigation = electrobun.allowAllNavigation,
    event             = electrobun.noopWebviewEvent,
    event_bridge      = electrobun.noopWebviewPostMessage,
  }


  if _, webview_err := electrobun.createWebview(g_core, webview_options); webview_err != .None {
    fmt.eprintfln("[hello] failed to create webview: %v", webview_err)
    _ = electrobun.closeWindow(g_core, window_id)
  }
}


main :: proc() {
  core, core_err := electrobun.load()
  if core_err != .None {
    fmt.eprintfln("[hello] failed to load Electrobun core: %v", core_err)
    return
  }
  defer electrobun.close(&core)


  bundle_paths, bundle_err := electrobun.resolveBundlePaths()
  if bundle_err != .None {
    fmt.eprintfln("[hello] failed to resolve bundle paths: %v", bundle_err)
    return
  }
  defer electrobun.deinit(&bundle_paths, context.allocator)


  owned_app_info, app_info_err := electrobun.resolveAppInfoFromBundle(context.allocator, &bundle_paths)
  if app_info_err != .None {
    fmt.eprintfln("[hello] failed to resolve app info: %v", app_info_err)
    return
  }
  defer electrobun.deinit(&owned_app_info, context.allocator)
  app_info := electrobun.borrowed(owned_app_info)


  g_core = &core
  g_bundle_paths = &bundle_paths
  defer g_core = nil


  thread.create_and_start(create_ui, self_cleanup = true)


  // Blocks running the native event loop until the app quits.
  if err := electrobun.runMainThread(&core, app_info); err != .None {
    fmt.eprintfln("[hello] main thread exited with error: %v", err)
  }
}
```

--------------------------------

### Initialize Window and Webview in Go

Source: https://framework.blackboard.sh/electrobun/apis/main

Create windows and webviews using the Go SDK, ensuring calls are made from the UI goroutine.

```go
// src/go/main.go — import "electrobun" through the project go.mod replacement
// to .hutch/devkit/go-sdk. Windows are created from a goroutine while
// RunMainThread blocks. Full setup in the Go hello world.
import "electrobun"


// ...inside the UI goroutine, after ConfigureWebviewRuntimeFromExecutableDir:
windowOptions := electrobun.NewWindowOptions(
    "My app",
    electrobun.NewRect(160, 100, 800, 600),
)
windowID, err := core.CreateWindow(windowOptions)


webviewOptions := electrobun.NewWebviewOptions(
    windowID,
    "views://mainview/index.html",
    electrobun.NewRect(0, 0, 800, 600),
)
_, err = core.CreateWebview(webviewOptions)
```

--------------------------------

### Install Hutch Canary on macOS or Linux

Source: https://framework.blackboard.sh/electrobun/guides/hutch

Install the canary channel alongside the production version to test prerelease builds.

```bash
curl -fsSL https://hutch.blackboard.sh/hutch/install.sh |
  sh -s -- --channel canary
```

--------------------------------

### Initialize Project Directory

Source: https://framework.blackboard.sh/electrobun/guides/hello-world-rust

Create and enter a new directory for the Rust-based Electrobun project.

```bash
mkdir my-rust-app
cd my-rust-app
```

--------------------------------

### Run the Electrobun Application

Source: https://framework.blackboard.sh/electrobun/guides/hello-world-odin

Use the hutch CLI to synchronize and launch the development environment.

```bash
hutch electrobun sync
hutch run dev
```

--------------------------------

### Bootstrap Native WGPU View

Source: https://framework.blackboard.sh/electrobun/apis/webgpu

Demonstrates the initialization of a WGPU view and the required main-thread-marshaled surface calls across supported native languages.

```zig
const wgpu_view_id = try core.createWGPUView(.{
    .window_id = window_id,
    .frame = .{ .x = 0, .y = 0, .width = 640, .height = 420 },
});


var native = try electrobun.WgpuNative.load(allocator);
defer native.close();
const context = try electrobun.WgpuContext.createForWgpuView(core, &native, wgpu_view_id);
const queue = context.getQueue(&native);


// Per-frame surface calls are marshaled to the main thread:
try core.wgpuSurfaceConfigureMainThread(context.surface_ptr, config_ptr);
try core.wgpuSurfaceGetCurrentTextureMainThread(context.surface_ptr, surface_texture_ptr);
_ = try core.wgpuSurfacePresentMainThread(context.surface_ptr);
```

```rust
let wgpu_view_id = core.create_wgpu_view(WGPUViewOptions::new(
    window_id,
    Rect::new(0.0, 0.0, 640.0, 420.0),
))?;


let native = WgpuNative::load()?;
let context = WgpuContext::create_for_wgpu_view(core, &native, wgpu_view_id)?;
let queue = context.get_queue(&native)?;


// Per-frame surface calls are marshaled to the main thread:
core.wgpu_surface_configure_main_thread(context.surface_ptr, config_ptr)?;
core.wgpu_surface_get_current_texture_main_thread(context.surface_ptr, surface_texture_ptr)?;
core.wgpu_surface_present_main_thread(context.surface_ptr)?;
```

```go
wgpuViewID, err := core.CreateWGPUView(electrobun.NewWGPUViewOptions(
    windowID,
    electrobun.NewRect(0, 0, 640, 420),
))


native, err := electrobun.LoadWgpuNative()
context, err := electrobun.CreateWgpuContextForWGPUView(core, native, wgpuViewID)
queue, err := context.GetQueue(native)


// Per-frame surface calls are marshaled to the main thread:
_ = core.WgpuSurfaceConfigureMainThread(context.Surface, configPtr)
_ = core.WgpuSurfaceGetCurrentTextureMainThread(context.Surface, surfaceTexturePtr)
_, _ = core.WgpuSurfacePresentMainThread(context.Surface)
```

```odin
wgpu_view_options := electrobun.defaultWGPUViewOptions(window_id)
wgpu_view_options.frame = {x = 0, y = 0, width = 640, height = 420}
wgpu_view_id, view_err := electrobun.createWGPUView(core, wgpu_view_options)


native, native_err := electrobun.wgpuNativeLoad()
ctx, ctx_err := electrobun.createForWgpuView(core, &native, wgpu_view_id)
queue := electrobun.getQueue(ctx, &native)


// Per-frame surface calls are marshaled to the main thread:
_ = electrobun.wgpuSurfaceConfigureMainThread(core, ctx.surface_ptr, &config)
_ = electrobun.wgpuSurfaceGetCurrentTextureMainThread(core, ctx.surface_ptr, &surface_texture)
_, _ = electrobun.wgpuSurfacePresentMainThread(core, ctx.surface_ptr)
```

--------------------------------

### Configure hutch.config.ts

Source: https://framework.blackboard.sh/electrobun/guides/hello-world

Define project tasks for installation, development, and building.

```typescript
export default {
  scripts: {
    install: ["hutch", "install", "--frozen-lockfile"],
    dev: ["hutch", "electrobun", "dev", "--watch"],
    build: ["hutch", "electrobun", "build", "--env=stable"],
  },
};
```

--------------------------------

### Initialize an Electrobun project

Source: https://framework.blackboard.sh/electrobun/apis/cli/cli-args

Various ways to invoke the init command, ranging from interactive mode to specific template and channel configurations.

```bash
# Interactive project name and template selection
hutch electrobun init


# Select a template directly
hutch electrobun init my-app --template=hello-world


# Use the beta template catalog
hutch electrobun init my-app --template=solid --beta


# Select stable instead of the invoking launcher's default catalog
hutch electrobun init my-app --template=solid --channel=stable


# Leave the template's install task for later
hutch electrobun init my-app --template=solid --skip-install
```

--------------------------------

### Initialize Project Directory

Source: https://framework.blackboard.sh/electrobun/guides/hello-world-zig

Commands to create and enter the project directory.

```bash
mkdir hello-zig
cd hello-zig
```

--------------------------------

### Initialize Window and Webview in Odin

Source: https://framework.blackboard.sh/electrobun/apis/main

Configure window and webview options using the Odin SDK and create them via the core instance.

```odin
// src/odin/main.odin — windows are created from a worker thread while
// runMainThread blocks. Full setup in the Odin hello world.
import electrobun "electrobun_sdk:electrobun"


// ...inside the UI thread, after configureWebviewRuntimeFromExecutableDir:
window_options := electrobun.defaultWindowOptions("My app")
window_options.frame = {x = 160, y = 100, width = 800, height = 600}
window_id, _ := electrobun.createWindow(core, window_options)


webview_options := electrobun.defaultWebviewOptions(window_id)
webview_options.url = "views://mainview/index.html"
webview_options.frame = {x = 0, y = 0, width = 800, height = 600}
electrobun.createWebview(core, webview_options)
```

--------------------------------

### Initialize Window and Webview in Zig

Source: https://framework.blackboard.sh/electrobun/apis/main

Create windows and webviews using the Zig SDK after configuring the runtime from the executable directory.

```zig
// src/zig/main.zig — the core is a dynamic library; windows are created
// from a worker thread while runMainThread blocks. Full setup in the
// Zig hello world.
const electrobun = @import("electrobun");


// ...inside the UI thread, after configureWebviewRuntimeFromExecutableDir:
const window_id = try core.createWindow(.{
    .title = "My app",
    .frame = .{ .x = 160, .y = 100, .width = 800, .height = 600 },
});


_ = try core.createWebview(.{
    .window_id = window_id,
    .url = "views://mainview/index.html",
    .frame = .{ .x = 0, .y = 0, .width = 800, .height = 600 },
    .callbacks = .{ .decide_navigation = electrobun.allowAllNavigation },
});
```

--------------------------------

### Configure Cottontail in Electrobun

Source: https://framework.blackboard.sh/electrobun/guides/native-main-process

Example configuration for the Cottontail runtime within an Electrobun project.

```typescript
import type { ElectrobunConfig } from "electrobun";


export default {
  app: {
    name: "Cottontail App",
    identifier: "dev.example.cottontail-app",
    version: "0.1.0",
  },
  build: {
    mainProcess: "cottontail",
    cottontail: { entrypoint: "src/bun/index.ts" },
  },
} satisfies ElectrobunConfig;
```

--------------------------------

### Define main process entrypoint

Source: https://framework.blackboard.sh/electrobun/guides/hello-world-bun

Initialize the main window using the Electrobun SDK.

```typescript
import { BrowserWindow } from "electrobun/main";


new BrowserWindow({
  title: "Hello Electrobun",
  url: "views://mainview/index.html",
  frame: {
    width: 800,
    height: 600,
    x: 200,
    y: 200,
  },
});
```

--------------------------------

### Create and Manage Webviews in Go

Source: https://framework.blackboard.sh/electrobun/apis/browser-view

Initialize webview options and perform navigation actions via the core interface.

```go
webviewOptions := electrobun.NewWebviewOptions(
    windowID,
    "views://details/index.html",
    electrobun.NewRect(320, 0, 680, 700),
)
webviewOptions.AutoResize = false
webviewID, err := core.CreateWebview(webviewOptions)


// Navigation and content:
_ = core.LoadURLInWebview(webviewID, "https://electrobun.dev")
_ = core.LoadHTMLInWebview(webviewID, "<h1>Inline content</h1>")
if core.CanWebviewGoBack(webviewID) {
    _ = core.WebviewGoBack(webviewID)
}
if core.CanWebviewGoForward(webviewID) {
    _ = core.WebviewGoForward(webviewID)
}
_ = core.ReloadWebview(webviewID)
_ = core.OpenWebviewDevtools(webviewID)
```

--------------------------------

### Initialize a New Project

Source: https://framework.blackboard.sh/electrobun/guides/quick-start

Commands to scaffold a new Electrobun project using the interactive picker or direct flags.

```shell
hutch electrobun init
```

```shell
hutch electrobun init my-app --template=hello-world
```

```shell
hutch electrobun init my-app --beta
```

--------------------------------

### Configure build scripts in hutch.config.ts

Source: https://framework.blackboard.sh/electrobun/guides/bundling-and-distribution

Defines the scripts for installing dependencies and building canary or stable release channels.

```typescript
export default {
  scripts: {
    install: ["hutch", "install", "--frozen-lockfile"],
    dev: ["hutch", "electrobun", "dev", "--watch"],
    "build:canary": ["hutch", "electrobun", "build", "--env=canary"],
    "build:stable": ["hutch", "electrobun", "build", "--env=stable"],
  },
};
```

--------------------------------

### Configure project scripts in hutch.config.ts

Source: https://framework.blackboard.sh/electrobun/apis/cli/cli-args

Defines custom scripts for building, installing, and running the application within the Hutch environment.

```typescript
export default {
  scripts: {
    install: ["hutch", "install", "--frozen-lockfile"],
    "ui:build":
      "hutch electrobun prepare && hutch pm exec -- vite build",
    start: ["hutch", "electrobun", "dev"],
    dev: ["hutch", "electrobun", "dev", "--watch"],
    "build:canary": ["hutch", "electrobun", "build", "--env=canary"],
    build: ["hutch", "electrobun", "build", "--env=stable"],
  },
};
```

--------------------------------

### Check and Install Updates

Source: https://framework.blackboard.sh/electrobun/apis/updater

Retrieve local version info, check for available updates, download them, and apply the update if ready.

```typescript
import { Updater } from "electrobun/main";


const local = await Updater.getLocalInfo();
console.log(`Running ${local.version} (${local.channel})`);


const update = await Updater.checkForUpdate();
if (update.updateAvailable) {
  await Updater.downloadUpdate();


  if (Updater.updateInfo().updateReady) {
    await Updater.applyUpdate();
  }
}
```

--------------------------------

### Initialize Native App Templates

Source: https://framework.blackboard.sh/electrobun/guides/native-main-process

Commands to generate boilerplate projects for various native languages.

```bash
hutch electrobun init zig-app --template=zig-wgpu
hutch electrobun init rust-app --template=rust-flock-wgpu
hutch electrobun init go-app --template=go-maze-wgpu
hutch electrobun init odin-app --template=odin-particles-wgpu
```

--------------------------------

### Building Electrobun Applications

Source: https://framework.blackboard.sh/electrobun/apis/cli/cli-args

Build the application for the current host platform using specific environment configurations.

```bash
hutch electrobun build --env=dev
hutch electrobun build --env=canary
hutch electrobun build --env=stable
```

--------------------------------

### Initialize BrowserWindow using electrobun/main

Source: https://framework.blackboard.sh/electrobun/apis/bun

Use the electrobun/main namespace for creating new windows in the main process.

```typescript
import { BrowserWindow } from "electrobun/main";


const win = new BrowserWindow({
  title: "My app",
  url: "views://mainview/index.html",
});


void win;
```

--------------------------------

### Initialize WebGPU Canvas Shim

Source: https://framework.blackboard.sh/electrobun/apis/webgpu

Install WebGPU globals and create a canvas shim for a GpuWindow to support browser-based rendering libraries.

```typescript
import { GpuWindow, webgpu } from "electrobun/main";


const win = new GpuWindow({
  title: "Library Integration",
  frame: { width: 960, height: 540 },
});


webgpu.install();
const canvas = webgpu.utils.createCanvasShim(win);
const context = canvas.getContext("webgpu");
if (!context) throw new Error("WebGPU context is unavailable");
```

--------------------------------

### Implement a postWrap Build Hook

Source: https://framework.blackboard.sh/electrobun/apis/cli/build-configuration

Example of a postWrap hook that accesses environment variables to perform file operations on the release wrapper.

```typescript
import { cpSync, existsSync } from "node:fs";
import { join } from "node:path";


const wrapper = process.env.ELECTROBUN_WRAPPER_BUNDLE_PATH;
if (!wrapper) throw new Error("This hook requires a release wrapper");


const source = "assets/release-only";
if (existsSync(source)) {
  cpSync(source, join(wrapper, "Contents", "Resources", "release-only"), {
    recursive: true,
  });
}
```

--------------------------------

### Create a Window and Webview in Odin

Source: https://framework.blackboard.sh/electrobun/apis/browser-window

Uses default options and manual frame configuration to create a window and webview.

```odin
window_options := electrobun.defaultWindowOptions("My app")
window_options.frame = {x = 160, y = 100, width = 960, height = 640}
window_id, window_err := electrobun.createWindow(core, window_options)


webview_options := electrobun.defaultWebviewOptions(window_id)
webview_options.url = "views://mainview/index.html"
webview_options.frame = {x = 0, y = 0, width = 960, height = 640}
webview_id, webview_err := electrobun.createWebview(core, webview_options)
```

--------------------------------

### Initialize Window and Webview in Rust

Source: https://framework.blackboard.sh/electrobun/apis/main

Use WindowOptions and WebviewOptions structs to define window properties and create the webview via the core instance.

```rust
// src/main.rs — the project Cargo.toml points `electrobun` at the Rust crate
// projected under .hutch/devkit. Full setup is in the Rust hello world.
use electrobun::{Core, Rect, WebviewOptions, WindowOptions};


// ...inside the UI thread, after configure_webview_runtime_from_executable_dir:
let window_options =
    WindowOptions::new("My app", Rect::new(160.0, 100.0, 800.0, 600.0));
let window_id = core.create_window(window_options)?;


let webview_options = WebviewOptions::new(
    window_id,
    "views://mainview/index.html",
    Rect::new(0.0, 0.0, 800.0, 600.0),
);
core.create_webview(webview_options)?;
```

--------------------------------

### Linux x64 Canary Artifact Structure

Source: https://framework.blackboard.sh/electrobun/guides/bundling-and-distribution

Example file structure for a Linux x64 canary build of an application named 'My Cool App'.

```text
artifacts/
|-- canary-linux-x64-update.json
|-- canary-linux-x64-MyCoolApp-canary-Setup.tar.gz
|-- canary-linux-x64-MyCoolApp-canary.tar.zst
`-- canary-linux-x64-<previous-hash>.patch
```

--------------------------------

### Initialize BrowserWindow with custom options

Source: https://framework.blackboard.sh/electrobun/apis/browser-window

Demonstrates creating windows with specific renderers or security sandboxing enabled.

```typescript
import { BrowserWindow } from "electrobun/main";


const cefWindow = new BrowserWindow({
  title: "CEF content",
  url: "views://mainview/index.html",
  renderer: "cef",
});


const sandboxedWindow = new BrowserWindow({
  title: "Untrusted content",
  url: "https://example.com",
  sandbox: true,
});


void cefWindow;
void sandboxedWindow;
```

--------------------------------

### Windows x64 Canary Artifact Structure

Source: https://framework.blackboard.sh/electrobun/guides/bundling-and-distribution

Example file structure for a Windows x64 canary build of an application named 'My Cool App'.

```text
artifacts/
|-- canary-win-x64-update.json
|-- canary-win-x64-MyCoolApp-Setup-canary.zip
|-- canary-win-x64-MyCoolApp-canary.tar.zst
`-- canary-win-x64-<previous-hash>.patch
```

--------------------------------

### Tray Lifecycle and Management

Source: https://framework.blackboard.sh/electrobun/apis/tray

Demonstrates initializing a tray, updating its properties, retrieving instance information, and removing the tray.

```typescript
import { Tray } from "electrobun/main";


const tray = new Tray({
  title: "Status",
  image: "views://assets/tray-icon.png",
});


tray.setTitle("Ready");
tray.setImage("views://assets/tray-ready.png");
tray.setVisible(false);
tray.setVisible(true);


const bounds = tray.getBounds();
const sameTray = Tray.getById(tray.id);
const allTrays = Tray.getAll();


void bounds;
void sameTray;
void allTrays;


tray.remove();
```

--------------------------------

### macOS ARM64 Canary Artifact Structure

Source: https://framework.blackboard.sh/electrobun/guides/bundling-and-distribution

Example file structure for a macOS ARM64 canary build of an application named 'My Cool App'.

```text
artifacts/
|-- canary-macos-arm64-update.json
|-- canary-macos-arm64-MyCoolApp-canary.dmg
|-- canary-macos-arm64-MyCoolApp-canary.app.tar.zst
`-- canary-macos-arm64-<previous-hash>.patch
```

--------------------------------

### Running Electrobun Applications

Source: https://framework.blackboard.sh/electrobun/apis/cli/cli-args

Launch an existing application bundle without triggering a new build.

```bash
hutch electrobun run --env=dev
```

--------------------------------

### Create and manage a tray with menu in TypeScript

Source: https://framework.blackboard.sh/electrobun/apis/tray

Use the Tray class to define an icon and menu. The menu must be installed before listening for interactions to ensure compatibility across platforms.

```typescript
import { Tray } from "electrobun/main";


const tray = new Tray({
  title: "My app",
  image: "views://assets/tray-icon.png",
  template: true,
  width: 32,
  height: 32,
});


const menuState: Record<string, boolean> = {
  notifications: true,
};


function updateTrayMenu() {
  tray.setMenu([
    {
      type: "normal",
      label: "Notifications",
      action: "notifications",
      checked: menuState.notifications,
    },
    { type: "separator" },
    {
      type: "normal",
      label: "Quit",
      action: "quit",
    },
  ]);
}


// Install the menu before listening for interaction. This is required for the
// supported Linux AppIndicator interaction path and works on every platform.
updateTrayMenu();


type TrayClickEvent = {
  data: { id: number; action: string; data?: unknown };
};


tray.on("tray-clicked", (event: unknown) => {
  const { action } = (event as TrayClickEvent).data;
  if (action === "notifications") {
    menuState.notifications = !menuState.notifications;
    updateTrayMenu();
  }
});
```

--------------------------------

### Init command usage syntax

Source: https://framework.blackboard.sh/electrobun/apis/cli/cli-args

The command-line argument structure for the init command.

```bash
hutch electrobun init [project-name] [--template=name]
  [--channel=stable|beta] [--beta] [--skip-install]
```

--------------------------------

### Initialize Main Process and Application Menu

Source: https://framework.blackboard.sh/electrobun/guides/creating-ui

Configures the application menu with standard system roles and initializes a browser window pointing to a local HTML file.

```typescript
import { ApplicationMenu, BrowserWindow } from "electrobun/main";


ApplicationMenu.setApplicationMenu([
  {
    label: "App",
    submenu: [{ role: "quit" }],
  },
  {
    label: "Edit",
    submenu: [
      { role: "undo" },
      { role: "redo" },
      { type: "separator" },
      { role: "cut" },
      { role: "copy" },
      { role: "paste" },
      { role: "selectAll" },
    ],
  },
]);


const win = new BrowserWindow({
  title: "My Browser",
  url: "views://main-ui/index.html",
  frame: { width: 1000, height: 700 },
});


void win;
```

--------------------------------

### new BrowserWindow(options)

Source: https://framework.blackboard.sh/electrobun/apis/browser-window

Creates a new native window instance. The constructor accepts an optional object containing configuration parameters for the window and its initial webview.

```APIDOC
## new BrowserWindow(options)

### Description
Creates a new native window instance. All options are optional, defaulting to a standard window if no arguments are provided.

### Parameters
#### Options
- **title** (string) - Optional - Native window title.
- **frame** (object) - Optional - Initial position and size { x, y, width, height }.
- **url** (string | null) - Optional - URL loaded by the initial webview.
- **html** (string | null) - Optional - HTML string loaded instead of url.
- **preload** (string | null) - Optional - Inline JavaScript or a bundled views:// script URL.
- **viewsRoot** (string | null) - Optional - Override for the bundled views root.
- **renderer** ("native" | "cef") - Optional - Renderer for the initial webview.
- **rpc** (RPC instance) - Optional - Main-process side of the webview RPC transport.
- **titleBarStyle** ("default" | "hidden" | "hiddenInset") - Optional - Native title-bar treatment.
- **styleMask** (object) - Optional - Advanced native style-mask overrides.
- **transparent** (boolean) - Optional - Make the native window background transparent.
- **passthrough** (boolean) - Optional - Pass pointer input through transparent regions.
- **spellCheck** (boolean) - Optional - Enable native spell checking.
- **hidden** (boolean) - Optional - Create without showing the window.
- **activate** (boolean) - Optional - Activate the window when it is created.
- **trafficLightOffset** (object) - Optional - macOS traffic-light offset { x, y }.
- **navigationRules** (string | null) - Optional - Serialized navigation policy.
- **sandbox** (boolean) - Optional - Disable RPC for untrusted content.
```

--------------------------------

### Initialize Window and Webview in TypeScript

Source: https://framework.blackboard.sh/electrobun/apis/main

Use the BrowserWindow and ApplicationMenu classes to set up the application window and menu. This applies to both Cottontail and Bun runtimes.

```typescript
// src/bun/index.ts — Cottontail executes TypeScript directly.
import { BrowserWindow, ApplicationMenu, Utils } from "electrobun/main";


const win = new BrowserWindow({
  title: "My app",
  url: "views://mainview/index.html",
});


ApplicationMenu.setApplicationMenu([
  { label: "File", submenu: [{ role: "quit" }] },
]);


Utils.showNotification({ title: "Application started" });
void win;
```

```typescript
// src/bun/index.ts — same TypeScript SDK, running on the actual Bun runtime.
import { BrowserWindow, ApplicationMenu, Utils } from "electrobun/main";


const win = new BrowserWindow({
  title: "My app",
  url: "views://mainview/index.html",
});


ApplicationMenu.setApplicationMenu([
  { label: "File", submenu: [{ role: "quit" }] },
]);


Utils.showNotification({ title: "Application started" });
void win;
```

--------------------------------

### Create a UI window

Source: https://framework.blackboard.sh/electrobun/apis/ui/overview

Initialize a new GPU-backed window with specified options and an application callback.

```typescript
const uiWindow = await createUIWindow(options, app);
```

--------------------------------

### Create a GPU Window and Context

Source: https://framework.blackboard.sh/electrobun/apis/webgpu

Initialize a native window and configure a WebGPU context for rendering.

```typescript
import { GpuWindow, webgpu } from "electrobun/main";


const win = new GpuWindow({
  title: "WebGPU",
  frame: { width: 800, height: 600 },
});


const created = webgpu.createContext(win);
const adapter = await webgpu.navigator.requestAdapter({
  compatibleSurface: created.context,
});
const device = await adapter.requestDevice();


created.context.configure({
  device,
  format: webgpu.navigator.getPreferredCanvasFormat(),
  alphaMode: "premultiplied",
});
```

--------------------------------

### hutch electrobun run

Source: https://framework.blackboard.sh/electrobun/apis/cli/cli-args

Launches an existing application bundle for a selected environment with optional inspection flags.

```APIDOC
## hutch electrobun run

### Description
Launches an existing application bundle without rebuilding. Supports main-process inspection for debugging.

### Parameters
#### Flags
- **--env** (string) - Optional - The environment to run.
- **--inspect** (string) - Optional - Enable main-process inspection (supports host:port syntax).
- **--inspect-wait** (string) - Optional - Enable inspection and wait for debugger connection.
- **--inspect-brk** (string) - Optional - Enable inspection and break on start.
- **--no-inspect** (boolean) - Optional - Disable configured inspection.
```

--------------------------------

### new Electroview(options)

Source: https://framework.blackboard.sh/electrobun/apis/browser/electroview-class

Initializes a new Electroview instance with the provided RPC configuration.

```APIDOC
## new Electroview(options)

### Description
Creates a new Electroview instance to manage the webview-side communication.

### Parameters
- **options** (object) - Required - Configuration object containing:
  - **rpc** (object) - Required - The RPC object returned by `Electroview.defineRPC`.
```

--------------------------------

### Tray Constructor

Source: https://framework.blackboard.sh/electrobun/apis/tray

Initializes a new Tray instance with specified configuration options.

```APIDOC
## new Tray(options)

### Description
Creates a new system tray icon.

### Parameters
- **title** (string) - Optional - Text shown by the tray backend.
- **image** (string) - Optional - views:// URL or absolute image path.
- **template** (boolean) - Optional - Treat the image as a macOS template image.
- **width** (number) - Optional - Requested image width.
- **height** (number) - Optional - Requested image height.
```

--------------------------------

### Define package.json

Source: https://framework.blackboard.sh/electrobun/guides/hello-world-bun

Set up the project metadata and dependencies.

```json
{
  "name": "my-app",
  "private": true,
  "type": "module",
  "devDependencies": {
    "@types/bun": "latest"
  }
}
```

--------------------------------

### Registering and initializing the WGPU element

Source: https://framework.blackboard.sh/electrobun/apis/browser/electrobun-wgpu-tag

Imports the necessary types and listens for the ready event to retrieve the native view ID.

```typescript
import type { WgpuTagElement } from "electrobun/view";
import "electrobun/view";


const surface = document.querySelector("electrobun-wgpu");
if (!surface) throw new Error("The WGPU surface was not found");


surface.on("ready", (event) => {
  const { id } = event.detail as { id: number };
  console.log("Native WGPU view ready", id);
});


const typedSurface: WgpuTagElement = surface;
void typedSurface;
```

--------------------------------

### Initialize the Electrobun Main Process

Source: https://framework.blackboard.sh/electrobun/guides/hello-world-go

Defines the main entry point and UI creation logic for an Electrobun application. Ensure the native event loop runs on the main goroutine as shown.

```go
package main


import (
  "fmt"
  "os"
  "time"


  "electrobun"
)


func main() {
  if err := run(); err != nil {
    fmt.Fprintf(os.Stderr, "[hello-go] %s\n", err)
    os.Exit(1)
  }
}


func run() error {
  core, err := electrobun.LoadCore()
  if err != nil {
    return err
  }
  bundlePaths, err := electrobun.ResolveBundlePaths()
  if err != nil {
    return err
  }
  appInfo, err := electrobun.ResolveAppInfoFromBundle(bundlePaths)
  if err != nil {
    return err
  }


  go createUI(core, bundlePaths)


  // Blocks on the native event loop; must run on the main goroutine.
  return core.RunMainThread(appInfo)
}


func createUI(core *electrobun.Core, bundlePaths electrobun.BundlePaths) {
  time.Sleep(150 * time.Millisecond)
  if err := core.ConfigureWebviewRuntimeFromExecutableDir(bundlePaths, 0); err != nil {
    fmt.Fprintf(os.Stderr, "[hello-go] failed to configure webview runtime: %s\n", err)
    return
  }


  windowOptions := electrobun.NewWindowOptions(
    "Hello Electrobun",
    electrobun.NewRect(140, 100, 800, 600),
  )
  windowOptions.Callbacks = electrobun.WindowCallbacks{
    Close: func(uint32) { _ = core.StopEventLoop() },
  }
  windowID, err := core.CreateWindow(windowOptions)
  if err != nil {
    fmt.Fprintf(os.Stderr, "[hello-go] failed to create window: %s\n", err)
    return
  }


  webviewOptions := electrobun.NewWebviewOptions(
    windowID,
    "views://mainview/index.html",
    electrobun.NewRect(0, 0, 800, 600),
  )
  if _, err := core.CreateWebview(webviewOptions); err != nil {
    fmt.Fprintf(os.Stderr, "[hello-go] failed to create webview: %s\n", err)
    _ = core.CloseWindow(windowID)
  }
}
```

--------------------------------

### Initialize Odin Graphics Templates

Source: https://framework.blackboard.sh/electrobun/guides/native-main-process

Commands to generate specialized Odin templates for graphics and physics simulations.

```bash
hutch electrobun init fluid-lab --template=odin-fluid-wgpu
hutch electrobun init jelly-lab --template=odin-jelly-bunny-wgpu
hutch electrobun init alchemy-lab --template=odin-alchemy-wgpu
hutch electrobun init tree-studio --template=odin-tree-wgpu
```

--------------------------------

### Create a Window and Webview in Rust

Source: https://framework.blackboard.sh/electrobun/apis/browser-window

Configures window and webview options before creating them via the core interface.

```rust
let mut window_options =
    WindowOptions::new("My app", Rect::new(160.0, 100.0, 960.0, 640.0));
window_options.callbacks = WindowCallbacks {
    close: Some(main_window_closed),
    ..WindowCallbacks::default()
};
let window_id = core.create_window(window_options)?;


let webview_options = WebviewOptions::new(
    window_id,
    "views://mainview/index.html",
    Rect::new(0.0, 0.0, 960.0, 640.0),
);
let webview_id = core.create_webview(webview_options)?;
```

--------------------------------

### Comparing memo and live for resource management

Source: https://framework.blackboard.sh/electrobun/apis/ui/reactivity

Shows how memo derives pure values while live manages side effects like WebSocket connections.

```javascript
const socketUrl = memo(() => `wss://${region()}/feed`);   // pure. just a value.


live(() => {
  const ws = new WebSocket(socketUrl());
  cleanup(() => ws.close());                              // owns the resource
});
```

--------------------------------

### Run development builds with Hutch

Source: https://framework.blackboard.sh/electrobun/apis/cli/cli-args

Commands to launch a development bundle, optionally with file watching enabled.

```bash
hutch electrobun dev
hutch electrobun dev --watch
```

--------------------------------

### Configure Electrobun build

Source: https://framework.blackboard.sh/electrobun/guides/hello-world-bun

Set the main process to use Bun and define build paths.

```typescript
import type { ElectrobunConfig } from "electrobun";


export default {
  app: {
    name: "My App",
    identifier: "dev.example.my-app",
    version: "0.0.1",
  },
  build: {
    mainProcess: "bun",
    bun: {
      entrypoint: "src/bun/index.ts",
    },
    copy: {
      "src/mainview/index.html": "views/mainview/index.html",
    },
  },
} satisfies ElectrobunConfig;
```
Tokens:
Raw