v5-plugins-development.md
A plugin is a directory with a static plugin.toml manifest and one or more Luau entry scripts. Each entry runs in its own isolated Luau VM, off the UI thread, with per-call time budgets - a slow or crashing script never stalls the shell. Plugins are trusted code: installing one is equivalent to running a user-owned script.
my-plugin/ plugin.toml # manifest: identity + entries + settings schema widget.luau # an entry script translations/en.json # optional i18n bundle (flattened, dotted keys) data.txt # any files your scripts read at runtime
The fastest way to learn the shape is the official-plugins repo: the example plugin shows a widget, a service, and a shortcut sharing state, and screen_recorder is a full real-world plugin.
Section titled “Development reference”
| Page | Use it for |
|---|---|
| Manifest & Settings | plugin.toml, entry declarations, and typed settings schemas |
| Entry Scripts | Luau lifecycle functions and APIs for widgets, shortcuts, and launcher providers |
| Declarative UI | desktopWidget.*, panel.*, and the shared ui.* control vocabulary |
| Runtime API | noctalia.* host capabilities and shared plugin state |
| Workflow & Publishing | Local development, IPC testing, source repos, and catalog metadata |
Section titled “Minimal widget”
id = "me/hello"name = "Hello"version = "1.0.0"min_noctalia = "5.0.0"author = "me"
[[widget]]id = "hello"entry = "widget.luau"
function update() noctalia.setUpdateInterval(1000) barWidget.setGlyph("puzzle") barWidget.setText("Hello")end
function onClick() noctalia.notify("Hello", "you clicked me")end