@usebely/sdk

Build plugins for Bely — the app launcher for Windows and Android.

Plugins are small React apps that run inside an isolated iframe. They can add new tools to the launcher, search providers, custom actions, and themes.

Install

pnpm add @usebely/sdk react react-dom

Quick Start

import { mount, List, useFetch } from "@usebely/sdk";
import { useState } from "react";

function App() {
  const [query, setQuery] = useState("");

  const { data, loading } = useFetch(
    query.length >= 2
      ? `https://api.example.com/search?q=${query}`
      : null
  );

  return (
    <List
      searchBarPlaceholder="Search..."
      onSearchChange={setQuery}
      isLoading={loading}
    >
      {data?.results?.map((item) => (
        <List.Item
          key={item.id}
          id={item.id}
          title={item.name}
          subtitle={item.description}
        />
      ))}
    </List>
  );
}

mount(<App />);

Components

| Component | Description | |-----------|-------------| | List | Searchable list with items, sections, and action panels | | Detail | Detail view with header, markdown, metadata, and actions | | Form | Form with text fields, dropdowns, and checkboxes | | Grid | Grid layout for visual items | | Action | Inline action buttons (copy, open URL, custom) | | ActionPanel | Container for multiple actions |

Hooks

| Hook | Description | |------|-------------| | useFetch | HTTP requests proxied through Rust (no CORS), built-in debounce | | useStorage | Sandboxed per-plugin localStorage | | useClipboard | Read/write clipboard (requires permission) | | useNavigation | Navigate back within the plugin | | usePluginContext | Access plugin ID, query, theme, locale | | useTranslation | Internationalize your plugin (en, pt-BR, es) | | useSystemInfo | Get OS info, theme, locale, Bely version |

Internationalization

import { useTranslation } from "@usebely/sdk";

const translations = {
  en: { search: "Search...", noResults: "No results" },
  "pt-BR": { search: "Buscar...", noResults: "Nenhum resultado" },
  es: { search: "Buscar...", noResults: "Sin resultados" },
};

function App() {
  const { t, locale } = useTranslation(translations);
  return <List searchBarPlaceholder={t("search")} />;
}

The hook resolves the best locale match (exact, then base language, then English fallback).

Theming

Plugins automatically inherit the user's theme. The host injects 40+ CSS variables into the iframe:

background: var(--glass-bg);
color: var(--glass-text);
border: 1px solid var(--glass-btn-border);

SDK components use these variables automatically. Only use them directly for custom styles.

Permissions

Plugins run in a sandboxed iframe. Declare required permissions in bely.plugin.json:

| Permission | Description | |------------|-------------| | fetch | Make HTTP requests (proxied, no CORS) | | clipboard.read | Read from clipboard | | clipboard.write | Write to clipboard | | fs.read | Read files from disk | | fs.write | Write files to disk | | system.info | Get OS info, theme, locale |

Storage and URL opening are always allowed without permissions.

Documentation

Full documentation at bely.my/docs/plugins.

License

MIT