Build on Sunflare

Writing plugins

Plugins are local, desktop-only scripts that extend the app: composer buttons and message menu items, panels with their own controls, saved data and settings, and text tools for the message box. No server, no publishing, no review process: install a .js file and it runs.

Install a plugin#

Settings → Plugins (desktop app only) has an Install Plugin button that opens a native file picker filtered to .js files. If the plugin asks for permissions, you're asked once whether to allow them. Each installed plugin gets a card with an on/off switch, a remove action, its permissions (each one a switch you can change any time), its own settings, and its last error if it hit one. Open Plugins Folder opens the actual folder on disk if you'd rather manage files by hand.

Anatomy of a plugin#

A plugin is one JavaScript file starting with a manifest comment block:

// ==SunflarePlugin==
// @id          your.unique.id
// @name        My Plugin
// @version     1.0.0
// @author      Your Name
// @description What it does, in one line
// @permission  messages
// ==/SunflarePlugin==

// your code goes here

Only @id is required. Install fails without it. Everything else defaults (name → "Untitled Plugin", version → "0.0.0", author → "Unknown"). All fields are length-capped, so keep them short. @permission is optional and can repeat or list several names separated by commas; see Permissions.

Your code runs in a Web Worker, so there's no document or DOM. Everything a worker normally has works: timers, Promise/async, JSON, Math, Intl, OffscreenCanvas. eval and new Function are blocked.

The sunflare API#

Inside a plugin, a global sunflare object is the entire surface you have to work with. sunflare.apiVersion is 2. Calls that return something return a Promise; one that isn't allowed rejects with an Error saying why.

Buttons and menu items#

Notifications and sound#

notify and toast share a budget of 10 per minute. Going over disables the plugin.

Storage#

A key/value store of your own, saved on this computer and kept until the plugin is removed. Values are anything JSON can hold. 256KB per plugin; keys up to 100 characters.

Settings#

Describe your settings once and the app draws them on your plugin's card in Settings → Plugins, saves them, and tells you when they change.

sunflare.settings.define([
  { key: 'greeting', type: 'text', label: 'Greeting', default: 'Hi!', maxLength: 50 },
  { key: 'loud', type: 'toggle', label: 'Also play a sound', default: false },
  { key: 'count', type: 'number', label: 'How many', min: 1, max: 10, step: 1, default: 3 },
  { key: 'style', type: 'select', label: 'Style', default: 'short',
options: [{ value: 'short', label: 'Short' }, { value: 'long', label: 'Long' }] }
]);
const values = await sunflare.settings.get();    // { greeting, loud, count, style }
sunflare.settings.onChange(values => { /* the user changed something */ });

Up to 12 fields. Each can also have a description. Values are checked against the field (numbers clamped to min/max, selects limited to their options), so you always get a valid one.

Panels#

A panel is a small floating card your plugin fills with controls. You describe it; the app draws it in its own style, with your plugin's name and a "Plugin" badge on top. Only one panel is open at a time.

blocks is a list of these (up to 60):

Events you get: { type: 'click', id } for buttons; { type: 'change', id, value } for text boxes (while typing, slightly delayed), toggles and selects; { type: 'submit', id, value } when Enter is pressed in a text box (Ctrl+Enter in a textarea); and { type: 'close' } when the user closes the panel.

While someone is typing in a text box, re-rendering the panel keeps what they typed. Add reset: true to that block when you really mean to replace it, such as clearing the box after a submit.

The message box#

A plugin can only ever put text in the box. Sending is always the user's choice. Text is capped at 2,000 characters per call.

The recent-click rule#

Opening a panel and anything that touches the message box only work within 5 seconds of the user clicking one of your own buttons, menu items, or panel controls. Nothing pops up or edits a draft on its own. Updating or closing a panel that's already open doesn't need a click.

Permissions#

Two things need the user's say-so. Ask for them with @permission in your manifest; they stay off until the user turns them on, and they can turn them off again on your card at any time.

await sunflare.permissions.list() gives the ones you hold right now; sunflare.permissions.has(name) checks one. Handle the "not allowed" case kindly: tell the user where to turn it on.

Examples#

All three live in public/plugins/ in the repo. Install any of them as-is.

Hello (the basics)#

// ==SunflarePlugin==
// @id          sunflare.example.hello
// @name        Hello Plugin
// @version     1.0.0
// @author      Sunflare
// @description Adds one composer button that fires a desktop notification.
// ==/SunflarePlugin==

sunflare.addComposerButton({ id: 'hello-btn', icon: 'star', title: 'Say hi' });
sunflare.onClick('hello-btn', () => {
  sunflare.notify({ title: 'Hello Plugin', body: 'Composer button clicked.' });
});

Quote (a permission)#

// ==SunflarePlugin==
// @id          sunflare.example.quote
// @name        Quote
// @version     1.0.0
// @author      Sunflare
// @description Right-click a message and choose Quote to put it in your message box.
// @permission  messages
// ==/SunflarePlugin==

sunflare.addContextMenuItem({ id: 'quote', label: 'Quote' });

sunflare.onClick('quote', async event => {
  if (!event.message) {
sunflare.toast('Turn on "Read a message" for Quote in Settings > Plugins to use this.');
return;
  }
  const { text, author } = event.message;
  const short = text.length > 300 ? text.slice(0, 300) + '...' : text;
  await sunflare.composer.insert(`"${short}" (${author.displayName}) `);
});

Snippets (storage, settings, a panel)#

A composer button that opens a panel of saved snippets: click one to drop it into the message box, or add a new one. See public/plugins/snippets-plugin.js for the full file.

What a plugin can't do#

This is enforced by the sandbox, not by convention. There's no bridge for any of it:

• Reach the network in any way. Plugin code runs in a Worker, which has no page to navigate and no WebRTC, and the sandbox's Content-Security-Policy blocks every request.
• See the app's page, your other messages, DMs, or anything a permission doesn't explicitly hand it
• Send a message, act on your behalf, or call any Sunflare API route
• Access your account, trust rank, subscription, or another plugin's data
• Put its own HTML or styles into the app. Panels and settings are drawn by the app from the fixed list of blocks above.
• Open a panel or touch your draft unless you just clicked it
• Touch the filesystem or any Node/Electron API

Limits worth knowing while building#

• 3 composer buttons and 3 context-menu items per plugin, maximum.
• 10 notifications and toasts per minute, combined. Going over disables the plugin, not just throttles it.
• 200 calls per second into the app, of any kind. Only a runaway loop gets near that, and it disables the plugin.
• 256KB of storage, 12 settings, 60 panel blocks, 2,000 characters of text per composer call or text box.
• Registering well past the button/menu-item cap repeatedly also auto-disables a plugin.
• Plugin files are capped at 2MB on install.
• Uncaught errors show on your plugin's card in Settings → Plugins, with a line number.

Upgrading a plugin from before panels#

Everything from the first version of the API works unchanged. The one difference: plugins now run in a Worker instead of a hidden page, so a plugin that used document or other page APIs needs to drop them. window still exists as an alias for the worker's global scope.

Distributing a plugin#

There's no store or publishing flow. Share the .js file however you like (a gist, a repo, a Sunflare server's file uploads). Anyone installing it goes through the same native file picker as any other install.