Modularium API

Type definitions for the Modularium plugin API.

Add them to a plugin project and import the Modularium type for autocomplete and type-checking:

import type { Modularium } from 'modularium';

export function activate(modularium: Modularium) {
  modularium.ui.toast('Hello from my plugin!');
}

For a complete, buildable example see the sample plugin.

Installing

Modularium's types aren't published to npm yet — reference this repo directly:

{
  "devDependencies": {
    "modularium": "github:dipilo/modularium-api"
  }
}

Plugin structure

A Modularium plugin is a folder under %APPDATA%/Modularium/plugins/<id>/ containing:

modularium-plugin.json (the manifest)

• apiVersion — currently 1.
• id — [a-z0-9_-], max 64 chars. Must match your entry in the community list.
• name — display name.
• version — dotted version, used for update detection.
• description — short summary.
• author, authorUrl — (optional) shown on the plugin card.
• fundingUrl — (optional) a donation link, or a { "Service": "url" } map. Shows a Donate button.
• minAppVersion — (optional) minimum Modularium version.
• entry — { "type": "js", "entry": "plugin.js" }.

plugin.js (the entry)

• Exports activate(modularium), and optionally onunload()/deactivate().
• Runs in the app's renderer with the injected modularium object — no bundler required, though the sample plugin shows a TypeScript + esbuild setup.

What you can do

By calling into the injected modularium object you can:

• Run headless actions (registerAction) and palette commands with hotkeys (addCommand).
• Add UI: pack actions (ui.addPackAction), Settings tabs (ui.addSettingsTab), top-bar buttons (ui.addToolbarButton), status-bar items (ui.addStatusBarItem), and toasts (ui.toast).
• Read packs (packs.list/packs.read) and fetch remote text (http.fetchText).
• Persist data: namespaced strings (settings) or a structured JSON blob (data.load/data.save).
• Register a content (search/install) source (providers.register).
• Extend other features via named extension points (contribute / getContributions), e.g. adding a crash signature with contribute('crashRule', …) or a critter with contribute('critter', …).

Lifecycle & disposal

Every register*/add*/on/contribute/providers.register call returns a disposer and is auto-tracked, so disabling or uninstalling your plugin fully reverses it — no app reload. For resources the API can't track (your own timers, global listeners), release them in onunload:

export function activate(modularium: Modularium) {
  const timer = setInterval(() => modularium.log('tick'), 60000);
  modularium.onunload(() => clearInterval(timer));
}

Or use the lifecycle-tied helpers that auto-dispose: registerInterval and registerDomEvent.

Issues and API requests

Please file issues and requests at https://github.com/dipilo/modularium-api/issues