简体中文 | English

Orbit

Orbit is a MoonBit-based desktop application framework. It combines native windows and event loops, an embedded system WebView, and capability-controlled IPC between a web frontend and a MoonBit backend.

Orbit does not require a specific frontend framework. A static HTML/CSS/ JavaScript application, React, Vue, and other Vite-based frontends can all be embedded.

Support

Windows x64 is the primary target.
Linux x64 is experimental and requires GTK3 and WebKitGTK 4.1.
macOS does not currently have an Orbit top-level window host.
Android is an optional preview host with a separate Activity/WebView runtime.

Prerequisites

MoonBit
A native C/C++ compiler and linker
Node.js 20 or newer when using the CLI or Vite
Windows: MSVC and the Windows SDK
Windows runtime: the Microsoft Edge WebView2 Evergreen Runtime when running the example directly with moon run
Linux: pkg-config, GTK3, and WebKitGTK 4.1 development packages

On Ubuntu or Debian, install the Linux WebView dependencies with:

sudo apt-get install build-essential pkg-config libgtk-3-dev libwebkit2gtk-4.1-dev

Headless Linux validation additionally needs xvfb; an interactive desktop run does not.

On Windows, the first native build downloads and verifies the WebView2 SDK. Set MOONVIEW_WEBVIEW2_SDK_DIR, or both MOONVIEW_WEBVIEW2_INCLUDE and MOONVIEW_WEBVIEW2_LOADER_LIB, for an offline or preinstalled SDK. The direct moon run example uses the installed Evergreen Runtime; packaged Windows installers can bootstrap it according to bundle.windows.webview_install_mode.

Run the repository example

git clone https://github.com/Nanaloveyuki/orbit.git
cd orbit
moon update
moon run orbit-example

The example opens a native window and serves an embedded WebView page. The page invokes example.ping and receives a JSON response from MoonBit.

Create an application

Use the CLI to create a new application without overwriting an existing path:

npx @nanaloveyuki/orbit-cli@alpha init my-orbit-app --name "My Orbit App" --identifier com.example.my-orbit-app --module example/my-orbit-app
cd my-orbit-app
moon update
npm install
npm run orbit:run

The generated application includes a native MoonBit entry point, a schema v2 configuration, embedded frontend resources, capability-protected IPC, and the scripts needed for development and production builds.

Add Orbit to an existing app

moon add Nanaloveyuki/orbit@0.1.0-alpha.15
npm install --save-dev @nanaloveyuki/orbit-cli@alpha
npx orbit generate
npx orbit dev

The CLI reads build and development commands from orbit.conf.json. It does not guess the frontend framework, package manager, development URL, or output directory.

Clipboard, shell, user directories, OS safe storage, auto-launch, keep-awake, and global hotkeys come from the experimental orbit-desktop extensions. Construct and inject only the extensions the application needs, then grant their commands to a local window. Importing the package does not enable them. Shell and directory commands return native paths to that authorized window.

Edit an application

Edit frontend files under the configured assets/ directory or the frontend source directory used by Vite.
Register MoonBit commands in a CommandRegistry.
Grant those commands to the intended page or window in ipc_policy.
Regenerate embedded resources after changing a non-Vite assets/ directory.
Run the application again and verify the IPC path.

For the repository example:

moon run --target native orbit-build orbit-example/orbit.conf.json orbit-example/generated_page.mbt
moon run orbit-example

The generated generated_page.mbt and orbit-bindings.mjs files describe the current embedded inputs. Review their diff when configuration or permissions change.

Register and call IPC

MoonBit backend:

let registry = @ipc.CommandRegistry::new()
registry.register_json(@ipc.CommandName::new("example.ping"), _payload => {
  Ok({ "message": "IPC round trip completed." })
})

Browser frontend:

const response = await window.__ORBIT__.invoke("example.ping", { value: 1 }, {
  timeout: 5000,
});

Commands are available only when the application policy grants them to the calling page. Keep filesystem, HTTP, plugin, and remote-page capabilities explicitly scoped.

Troubleshooting

`moon update` or dependency download fails

Check the MoonBit version in .moon-version, confirm network access, and retry with a clean project-level dependency state. Do not edit generated dependency files by hand.

Windows native build cannot find WebView2

For native build failures, install the Windows SDK and allow MoonView to download its pinned WebView2 SDK, or set MOONVIEW_WEBVIEW2_SDK_DIR. If using separate paths, set both MOONVIEW_WEBVIEW2_INCLUDE and MOONVIEW_WEBVIEW2_LOADER_LIB. For runtime failures, install the Microsoft Edge WebView2 Evergreen Runtime.

Linux cannot create a WebView

Install a native C/C++ toolchain, pkg-config, GTK3, and WebKitGTK 4.1 development packages. For headless validation, also install xvfb. For a Vite application, run the frontend build separately and confirm that dist_dir matches the directory in orbit.conf.json.

Frontend changes are not visible

Development mode loads the configured Vite dev_url. Embedded production mode loads generated resources, so rerun orbit generate or orbit-build after changing the source assets.

An IPC call is denied or times out

Check the command name, the page origin, the principal in ipc_policy, and the configured timeout. Use npx orbit diagnose --json to inspect the local host and build environment without exporting IPC payloads.

Documentation

License

Orbit is licensed under the Apache License 2.0.