Workflow & Publishing

Beta - APIs may still change

The plugin system is in beta. The manifest format and APIs may still change before v5 is stable, so build with that in mind.

Local development

Drop your plugin under $XDG_DATA_HOME/noctalia/plugins/<plugin>/ (or add a path source pointing at your dev directory), then enable it once. Edits to .luau files hot-reload automatically; manifest changes are picked up on the next config reload. Drive an entry’s onIpc handler from the shell to test:

Source precedence

A plugin id is canonical - only one copy of a given author/plugin ever loads. When the same id ships from more than one source, the highest-precedence copy wins: the local data dir overrides everything, a later-added source overrides an earlier one, and user sources override the built-in official/community sources. So you can clone the official or community repo, add it as a source, and edit plugins in place to override the built-in copies - no need to rename ids. (Working on a single plugin? The data-dir drop-in above is simplest and outranks all sources.)

# A bar widget - target a specific output (focused / connector / a-bar-name) or all:
noctalia msg plugin me/hello:hello focused greet "hi there"

# A service - it is a singleton with no output, so address it with the `all` target:
noctalia msg plugin me/hello:ticker all refresh

# A panel - toggle by full entry id:
noctalia msg panel-toggle me/hello:panel

The target picks which live instances receive the event: focused (the focused output), a connector or <connector>:<bar-name>, or all. Services and other non-bar entries have no output, so they only match all.

Publishing

Plugins are distributed from source repos - one repo holds many plugins, each in its own subdirectory matching the part of the id after the / (so me/hello lives at hello/). Add a catalog.toml at the repo root indexing every plugin so it can be listed and compat-checked without a full clone:

[[plugin]]
id           = "me/hello"
name         = "Hello"
version      = "1.0.0"
author       = "me"
license      = "MIT"
icon         = "puzzle"
description  = "A friendly greeter."
deprecated   = false
min_noctalia = "5.0.0"
tags         = ["demo"]
dependencies = ["slurp"]

Catalog rows require id and name; rows without either are ignored.

Users add your repo with noctalia msg plugins source add <name> git <url>, then enable plugins from it. To contribute to the official catalog, open a PR against official-plugins.