Your first plugin

Install the CLI

npm install -g @fluxta/cli

This puts the fluxta command on your PATH. Every command it ships is listed in the CLI reference.

Create the plugin

fluxta create

It first asks for the plugin's name. Use a short, lowercase, URL-safe name such as my-plugin or hello-world. The name has to stay the same for the life of the plugin — Fluxta uses it to tell your plugin apart from every other one, and to find the settings it saved last time.

It then asks for an author, a short description, the categories users will find the plugin under in the Marketplace, and the platforms it runs on. create writes the project into a new directory named after the plugin, initializes a git repository, and runs pnpm install.

cd my-plugin

Look at what you got

manifest.json declares one Action named "Hello". apps/plugin/src/index.ts implements it. apps/editor/src/App.tsx is the form the user fills in when they configure it. Those three files are the whole plugin; the rest of the generated project is tooling — workspace config, lint and format setup, and a release workflow.

A few Package Metadata fields — repository, homepage, maintainers — start out empty. They only matter when you publish, and fluxta publish fills most of them in on its own, so leave them for now.

Start the dev loop

pnpm dev

This builds both halves, then watches them. Every time the background process rebuilds, it runs fluxta restart, which hands the freshly built folder to Fluxta and restarts the plugin there. Leave it running while you work.

The plugin is now installed in Fluxta.

Put it on your deck

In Fluxta, edit any button, add the Hello Action to it, and save. Press the button.

Nothing visible happens, which is correct: the generated Action writes a line to its log instead of touching the UI. Open the log to see it:

tail -f dist/my-plugin/logs/my-plugin.log

Press the button again and a line appears:

item 1: Hello from Fluxta!

Anything the background process writes to console.log or console.error lands in that file. It is the main window into a running plugin.

Change something

Open the button's settings again. The Message field is the generated Action Editor — apps/editor/src/App.tsx. Type something else and save, then press the button. The new text shows up in the log.

That is the whole loop: the editor saves settings, Fluxta stores them, and the background process receives them when the Action is triggered.

Now change the code. apps/plugin/src/index.ts holds the Action class, and onTrigger is the method Fluxta calls when the button is pressed. Make it shout:

class HelloAction extends ItemAction<HelloSettings> {
  type = "hello"; // === the manifest's `type`

  onTrigger(ctx: ItemTriggerContext<HelloSettings>) {
    console.log(
      `item ${ctx.itemId}: ${(ctx.settings.message ?? "Hello from Fluxta!").toUpperCase()}`,
    );
  }
}

Save. pnpm dev rebuilds and restarts the plugin automatically — no reload, no restarting Fluxta. Press the button and the log shows the change.