🎈 Vaelo — Microscopic, Zero-Dependency Desktop Application Framework

Vaelo is a lightweight, cross-compilable native desktop application runtime utilizing a statically embedded Go backend and native system browsers in application mode. It serves as a microscopic, zero-dependency alternative to Electron.

Unlike Electron, which bundles a heavy Chromium browser and Node.js runtime (~100MB+ overhead), Vaelo compiles into a single, size-optimized native binary (less than 7MB) that starts instantly, runs on native webview runtimes, and requires zero compiler toolchains for cross-compilation.

🚀 Key Features

• ⚡ Zero-CGO Cross-Compilation (Template Bypass): Ship precompiled binaries in bin/ templates. Package macOS .app bundles from Windows, or Windows .exe files from macOS in under 1 second without compilers!
• 🎈 Microscopic Binary Footprint: Statically compiled Go runtime weighing < 7MB. Combine it with the UPX compression utility to shrink your executable down to < 2MB!
• 🖥️ Native Window Frame: Renders web assets using native platform browsers in application mode (WebKit/Cocoa on macOS, WebView2 on Windows) for maximum system integration.
• 🔌 Unified OS SDK Bridge: A built-in asynchronous JavaScript API (window.Vaelo) exposing system file dialogs, clipboard read/writes, terminal runner, power monitoring, and release updater.
• 🔒 Secure CORS-Free Proxy Tunnel: Route local NoSQL database requests (like loftyDB) securely through Vaelo's Go backend to prevent webview security/CORS blocks.
• 🍉 Modern Menu Bars: Integrates native App Menus (File, View [Reload App], Window) on macOS using an Objective-C runtime bridge, complete with hidden titles to avoid layout overlaps.

🛠️ Prerequisites

To run development mode from source, ensure you have:

1. Go (version 1.18 or higher) - Download Go
2. Node.js (version 16 or higher) - Download Node.js

(No compilers or Go SDK are required to package/build projects if using the pre-compiled template binaries).

✨ Getting Started

Create and run a brand new Vaelo desktop application instantly:

# 1. Initialize a new project boilerplate
node cli/vaelo.js init my-desktop-app

# 2. Navigate to the project folder
cd my-desktop-app

# 3. Start in Development Mode (Serves local web resources with hot reload)
npm start

# 4. Package as a Standalone Executable (Bypasses compilers using templates!)
npm run build

📂 Project Structure

A newly initialized Vaelo project is organized as follows:

my-desktop-app/
├── package.json         # NPM scripts mapping (start, build)
├── README.md            # App developer guide
├── cli/
│   └── vaelo.js         # The compiler/packager orchestrator
├── bin/                 # Precompiled platform engine templates
│   ├── engine_darwin_amd64
│   ├── engine_darwin_arm64
│   └── engine_windows_amd64.exe
├── runtime/             # Native Go app engine (advanced customization)
│   ├── main.go          # HTTP RPC server & WebView container bootstrapper
│   ├── menu_darwin.go   # macOS Cocoa Menu hooks
│   ├── menu_darwin.m    # Objective-C Cocoa top menu bar logic
│   └── menu_other.go    # Stubs for Windows/Linux compilation
└── runtime/web/         # Your Web frontend workspace (HTML, CSS, JS)
    ├── index.html       # UI Markup
    ├── app.js           # Client SDK Bridge (window.Vaelo)
    └── logo.jpg         # Application Window Icon

🔌 JS API Documentation (window.Vaelo)

Vaelo automatically injects the window.Vaelo client bridge into your web application to communicate securely with the host operating system:

1. Get System OS Info

Returns the host OS platform and CPU architecture running the backend.

const osInfo = await window.Vaelo.getOS();
console.log(osInfo); // "darwin_arm64", "windows_amd64", etc.

2. Write Local File

Writes content directly to a file on the host machine relative to the executable's directory.

await window.Vaelo.writeFile("my_file.txt", "Hello from Vaelo!");

3. Execute Terminal Commands

Runs a shell command on the host OS and returns stdout/stderr.

const output = await window.Vaelo.runCommand("ping -c 3 google.com");

4. Show Native OS Alert Box

Displays a native system alert dialog.

await window.Vaelo.showAlert("Alert Title", "This is a native alert box!");

5. Open / Save Native File Dialogs

Prompts the user to select or save files using OS native file selectors.

// Open File
const filePath = await window.Vaelo.showOpenFileDialog();

// Save File
const savePath = await window.Vaelo.showSaveFileDialog("default_filename.txt");

6. Read / Write System Clipboard

Interacts directly with the OS system clipboard.

// Copy Text
await window.Vaelo.writeClipboard("Copied from frontend!");

// Read Text
const clipboardText = await window.Vaelo.readClipboard();

7. Query Native Battery & Power Status

Reads local hardware charge levels and power source states.

const power = await window.Vaelo.getPowerStatus();
console.log(power.percent);   // e.g. 85
console.log(power.onBattery);  // true if running on battery (unplugged)

🗄️ Database Integration

Vaelo supports two pathways for local database integration:

1. Embedded SQLite (Go Backend)

Include Go-SQLite drivers (like modernc.org/sqlite) inside the runtime/ folder. Register a query handler case inside main.go, and call it from the frontend:

const users = await window.Vaelo.call("getUsers", { role: "admin" });

2. Direct NoSQL (loftyDB Integration)

To avoid CORS blocks when fetching local database APIs (like loftyDB running on localhost:8080), you can route requests through Vaelo's secure backend tunnel:

// Get documents via loftyDB proxy tunnel
const notes = await window.Vaelo.call("loftyRequest", {
    method: "POST",
    path: "/api/collections/notes/query",
    body: {}
});

📦 Packaging and Distribution

Vaelo supports two modes of packaging and distribution:

Mode 1: Pre-compiled Template Build (Default)

Cross-compile instantly for other operating systems from any host machine in under 1 second without installing any local compiler toolchains (bypasses compilers using binary templates in bin/):

Build for macOS (Intel & Apple Silicon):

node cli/vaelo.js build --os darwin --arch arm64

Creates a native macOS App Bundle (VaeloApp.app). All frontend resources are packaged internally inside the bundle structure.

Package as macOS DMG Installer:

# Packages the app bundle along with a /Applications shortcut into a mountable disk image
node cli/vaelo.js build --os darwin --dmg

Appends a compressed, mountable disk image (VaeloApp.dmg) containing the built .app bundle and an installer shortcut to the system /Applications folder.

Build for Windows:

node cli/vaelo.js build --os windows --arch amd64

Creates app.exe along with a sibling resources/ folder containing frontend assets. Note: You must copy/distribute both the executable and the resources/ folder together.

Build for Linux:

node cli/vaelo.js build --os linux --arch amd64

Mode 2: Compile from Source (Standalone Single Executable)

Force the CLI to compile the Go engine from source, embedding all web assets directly inside a single standalone executable.

• Requirements: Requires Go compiler and target-specific cross-compilers (e.g. MinGW-w64 or Zig) installed on the host machine.
• Advantage: Zero external files. You only need to distribute the single standalone executable.
• Embedded Brand Icon: Automatically resizes and compiles web/logo.jpg into a native Windows .ico and embeds it directly inside the executable binary using Go resources (rsrc).

Build from source:

# Force CGO compilation and embed assets directly inside the binary
node cli/vaelo.js build --os windows --arch amd64 --compile

Creates a self-contained app.exe with your custom app icon embedded, running completely standalone without requiring any external resources/ folder.

🏷️ Keywords (NPM / SEO)

desktop-framework lightweight-electron golang-webview cross-platform-packaging zero-cgo embedded-webview loftyDB desktop-apps html-css-js-desktop native-menus micro-executables cgo-free-packaging

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.