Bubbledesk Bridge Overview

The Bubbledesk Bridge serves as a seamless integration layer between the JavaScript frontend and the Rust backend of the Bubbledesk application. It enables secure and efficient communication, allowing frontend code to invoke backend functionalities and access native capabilities.

This bridge exposes a set of modules and methods that can be accessed via the global window.Bubbledesk object, providing a unified API surface for interacting with the underlying Rust logic.

Lifecycle

The Bubbledesk Bridge instance window.Bubbledesk follows a defined lifecycle to ensure reliable availability and interaction:

• Bubbledesk.isAvailable
  A boolean flag indicating whether the bridge is currently available in the environment. This can be used to conditionally enable features that rely on the bridge.

• Bubbledesk.ready
  A Promise that resolves when the bridge is fully initialized and ready to be used. It is recommended to await this before making any calls to the bridge.

• Bubbledesk.isDesktop
  A Promise that resolves into a boolean flag that indicates whether the app is running inside the Bubbledesk desktop wrapper.
  When true, it means the web app is executing in the native desktop environment with access to the Bubbledesk bridge and native APIs.
  When false, the app is running in a regular browser and no native features are available.
  Use this flag to conditionally enable or disable features that depend on native integrations.

• Bubbledesk.<module_name>.<method>()
  Represents any specific function exposed by a bridge module. Each module provides its own set of callable methods that interact directly with native Rust commands.

• Bubbledesk.invoke()
  A low-level method to call backend functions directly by name with parameters. Useful for advanced use cases or when accessing less common APIs.

• Bubbledesk.version
  Returns the current version of Bubbledesk Bridge.

Example Usage

Here is a practical example demonstrating how to initialize the bridge and send a notification:

await Bubbledesk.ready;
// you can also assign the instance to a constant
// eg. `const bd = window.Bubbledesk;`

// then if ready you can call a module, for example:
await Bubbledesk.app.info();

Modules

Module	Description
app	Control application-level behaviors and retrieve app information.
notifications	Manage system notifications, including sending and scheduling notifications.
clipboard	Read from and write to the system clipboard.
files	Access and manipulate files on the local filesystem.
window	Control and query application window behaviors (resize, focus, etc.).
events	Listen for and emit custom or system events.
globalShortcut	Register and handle global keyboard shortcuts.
fs	Provides a dadicated filesystem for the app.
menu	Manage and update application native menus.
diagnostics	Access diagnostic tools and logs for troubleshooting.
network	Perform network requests and monitor connectivity state.
autostart	Manage application auto-start behavior on system login.
badge	Set the application badge count (macOS only).
worker	Run background tasks in worker threads.
contextMenu	Create and manage context (right-click) menus.

Platform Notes

• The badge functionality, which allows setting an application badge count, is currently supported only on macOS.

TIP

Best Practice: Always wait for Bubbledesk.ready to start using the bridge and invoking any methods to ensure the bridge is fully initialized.

WARNING

Cross-Platform Limitations: Some modules and features may behave differently or be unavailable depending on the operating system. Always check for availability and handle fallback logic gracefully.

For detailed usage please check API Reference