Skip to content

Plugin Development

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.

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

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