Publishing

There are two ways to get a plugin onto someone else's machine:

• The Marketplace — the plugin is reviewed once, then users find and install it from inside Fluxta. This is the path most plugins should take.
• On your own — you hand out a zip and users install it by hand. Useful for a private plugin, an internal tool, or a beta.

1. Fill in the metadata

Publishing needs more from the manifest than development does. Alongside the runtime fields, a publishable plugin carries:

repository and homepage are optional. Set either to show a link in the Marketplace; publishing does not require them.

fluxta create fills in author, minAppVersion, categories, and platforms from your answers, writes license as MIT, and leaves repository, homepage, and maintainers empty. fluxta publish fills in two of those for you:

• maintainers — from the GitHub account you authenticate as, since a CODEOWNERS entry has to be a verified identity.
• repository — from the package's own origin git remote, when neither repository nor homepage is already set.

Anything still missing at validation time is reported per field. So is any value left as a TODO placeholder.

minAppVersion declares the oldest Fluxta that can run this plugin. Raise it when the plugin starts using something new.

2a. Publish to the Marketplace

pnpm build
fluxta publish

publish validates everything, runs the project's own lint and format:check scripts if it has them, authenticates with GitHub — a one-time browser prompt; later runs reuse it — and opens a pull request against the public plugin repository, plugins, adding the plugin's source under plugins/<your-plugin-id>/. A failing lint or format check stops it before anything reaches GitHub; run pnpm lint or pnpm format and retry.

Useful flags:

• --base <branch> targets a branch other than the repository's default.
• --warnings-as-errors fails the command on advisory warnings too.

For the same strict validation with no GitHub interaction at all — in your own CI, say — use fluxta validate instead.

2b. Distribute it yourself

To hand out a plugin without going through the Marketplace, build a zip:

pnpm build
fluxta package --out my-plugin-1.0.0.zip

package runs the same full publishable validation, then writes a deterministic archive containing one top-level folder named after the plugin. It refuses to overwrite an existing file unless --force is passed.

Users install it by unpacking that folder into Fluxta's plugins directory and restarting the app:

The generated project also ships a GitHub Actions workflow for exactly this. Push a commit that bumps version in manifest.json, and it builds, packages, tags, and opens a draft GitHub Release with the zip attached, for you to review and publish by hand. This is independent of fluxta publish — use either, or both.

After a release

Once the pull request is merged, the release is built and published automatically, and the plugin shows up in the in-app Marketplace. Two consequences are worth knowing while you are still writing code:

• A published version is permanent. Its version number is never reused, even if the release is later withdrawn. Users are offered the newest published version and cannot pick an older one, so a bad release is fixed by publishing a higher version, never by pulling the broken one.
• Compatibility is enforced by the app, not the Marketplace. A plugin that needs a newer Fluxta than the user has stays visible with its requirement shown, rather than quietly disappearing. That is what minAppVersion and the manifest's apiVersion are for. The one exception is platforms: a plugin is not listed at all on a system it does not declare, since nothing the user does could make it run there.

Releasing an update

Bump version in manifest.json, rebuild, and publish again. Use SemVer, and remember that the version shipped last time is frozen — the only way forward is up.

An update is offered only to users who can run it. If the new version raises minAppVersion or drops a system from platforms, users it no longer fits keep the version they have: it stays installed and running, and the Marketplace shows why the update is not available instead of offering it.