community-plugins/README.md

# Community plugins

<p align="center">
  <img src="https://assets.noctalia.dev/noctalia-logo.svg?v=2" alt="Noctalia Logo" style="width: 192px" />
</p>

---

This repo is the **community** plugin source for [Noctalia](https://github.com/noctalia-dev/noctalia). Every
plugin merged here is listed in the shell's plugin store and on
[noctalia.dev/plugins](https://noctalia.dev/plugins), and users can install it without adding a source of their own.

Plugins maintained by the core team live in
[official-plugins](https://github.com/noctalia-dev/official-plugins), which does not accept third-party plugins.
This one does. **PRs are welcome.**

> The plugin system is in **beta**. The manifest format and the plugin API may still change before v5 is stable.
> Expect to bump your plugin when they do.

## Layout

Each plugin is **one top-level directory**, named after the part of its id that follows the `/`, so `me/hello` lives
in `hello/`:

```
hello/
  plugin.toml             # manifest: id ("me/hello"), metadata, entries, settings
  hello.luau              # your entry scripts
  README.md               # rendered as the plugin's page on noctalia.dev
  thumbnail.webp          # the plugin's card image
  translations/
    en.json               # every label_key / description_key the manifest references
```

`catalog.toml` at the repo root indexes every plugin. **It is generated by CI, so never edit it or include it in a
commit.**

A plugin id is `<author>/<plugin>`. The author part is yours (your GitHub handle is the obvious choice) and keeps your
id distinct from everyone else's, but the **directory name is first-come within this repo**. If `weather/` is already
taken, pick another name; the official repo is a separate source, so a name used there is not taken here. Both id
segments must be lowercase and match `[a-z0-9][a-z0-9._-]*`.

## What a plugin is allowed to be

Noctalia plugins are **trusted, unsandboxed Luau**. There is no permission broker and no capability sandbox:
installing a plugin is equivalent to running a script the user owns. It can read and write files, spawn processes, and
talk to the network as the user.

That is a deliberate design choice, and it puts the burden on review. So:

- **No obfuscated, minified, or generated code.** A reviewer must be able to read every line you ship.
- **No downloading and executing remote code.** Ship your logic in the repo, at a version people reviewed.
- **Declare what you shell out to.** External commands go in `dependencies` in `plugin.toml` and get a mention in your
  README.
- **Account for every network call, filesystem write, and spawned process** in your PR description.

Anything that looks like it is hiding what it does will be rejected, regardless of intent.

## Writing a plugin

The [plugin development docs](https://docs.noctalia.dev/v5/plugins/development/) are the reference: the
[manifest](https://docs.noctalia.dev/v5/plugins/development/manifest/), the
[entry types](https://docs.noctalia.dev/v5/plugins/development/entries/) (`[[widget]]`, `[[panel]]`, `[[shortcut]]`,
`[[service]]`, `[[desktop_widget]]`, `[[launcher_provider]]`), the
[declarative UI](https://docs.noctalia.dev/v5/plugins/development/declarative-ui/) vocabulary, the
[runtime API](https://docs.noctalia.dev/v5/plugins/development/runtime-api/), and the
[workflow](https://docs.noctalia.dev/v5/plugins/development/workflow/) for developing and testing locally.

The fastest start is to read
[`noctalia/example`](https://github.com/noctalia-dev/official-plugins/tree/main/example) in the official repo. It
exercises a bar widget, a declarative widget, a service, a shortcut, a launcher provider, and a panel in one plugin.

To run your plugin while you work on it, add this checkout as a `path` source:

```sh
noctalia msg plugins source add dev path ~/dev/community-plugins
noctalia msg plugins enable me/hello
```

`.luau` edits hot-reload; manifest changes are picked up on the next config reload.

### Editor setup

`noctalia.d.luau` declares the whole plugin API, so luau-lsp gives you autocomplete and typo diagnostics. It lives in
official-plugins, which is its single source of truth; it is **not** vendored here, because a committed copy would be a
second one for everyone to trust and keep in sync. Fetch it into the repo root, where it is gitignored:

```sh
curl -O https://raw.githubusercontent.com/noctalia-dev/official-plugins/main/noctalia.d.luau
```

Re-run that whenever the plugin API changes; your local copy is a snapshot, not a subscription.

The committed `.vscode/settings.json` already points luau-lsp at it; for another editor, add it to luau-lsp's
`types.definitionFiles`. `.luaurc` sets `nonstrict` mode, matching the `--!nonstrict` directive every plugin file
starts with.

### Thumbnail

Every plugin ships a `thumbnail.webp`. It is the card image in the plugin store and on the website. Generate one with
the **[thumbnail generator](https://assets.noctalia.dev/plugins/thumbnail-generator.html)**: drop in a screenshot of
your plugin, set the title, category tag and accent color, then export the 960×540 WebP and commit it as
`<plugin>/thumbnail.webp`.

### Translations

Write `translations/en.json` only. Every `label_key` and `description_key` in your manifest must resolve to a key in
it, and CI checks this. Do not add machine-translated locales; other languages are handled separately.

### Tags

The `tags` in `plugin.toml` are used for catalog search. Tags must be lowercase and selected from this list:

- Surfaces: `bar`, `desktop`, `launcher`, `panel`, `service`, `shortcut`
- Purpose: `ai`, `animation`, `audio`, `clock`, `countdown`, `demo`, `development`, `emoticon`, `fun`, `gaming`,
  `hardware`, `indicator`, `language`, `media`, `music`, `network`, `privacy`, `productivity`, `recording`, `system`,
  `theming`, `time`, `utility`, `video`, `wallpaper`
- Compositors: `hyprland`, `labwc`, `mangowc`, `niri`, `sway`
- Distributions: `arch`, `debian`, `fedora`, `gentoo`, `nixos`, `opensuse`, `void`

If your plugin does not fit any existing tag, propose a new one in your pull request rather than inventing a tag in
the manifest.

## Submitting

Open a PR against `main`. CI validates your manifest, entry scripts, required files, and thumbnail on every push.

- **One plugin per PR.**
- The directory name matches the part of `id` after the `/` in `plugin.toml` **exactly**.
- `version` is semver and gets bumped on every change to the plugin.
- `min_noctalia` is the Noctalia version you actually tested against. Users on older builds are then told the plugin
  needs an upgrade instead of getting a broken install.
- `license` is set in `plugin.toml`. You keep the copyright on your plugin; if it is not MIT, put a `LICENSE` file in
  your plugin directory. There is no repo-wide license covering contributed plugins.
- Screenshots or a short video for anything with a visual surface.

Maintainers read the code before merging. Expect review comments about clarity, and about anything the plugin does
that is not obvious from its description.

## Maintaining your plugin

The plugin directory is yours. Someone else's PR changing your plugin is not merged without your sign-off, unless it
fixes something that is broken or is a mechanical change applied across the whole repo. Maintainers will @-mention you
on PRs and issues that touch it.

If you stop maintaining a plugin, set `deprecated = true` in its `plugin.toml` rather than deleting the directory. The
store keeps working for people who already installed it, but it stops being offered to new users. Plugins that are
broken and unmaintained across a Noctalia release may be deprecated by maintainers.

## Help

- [Documentation](https://docs.noctalia.dev)
- [Discord](https://discord.noctalia.dev)
- Bugs in Noctalia itself (not in a plugin) belong in
  [noctalia](https://github.com/noctalia-dev/noctalia/issues).