Plugin System

Create, load, and publish plugins that extend Floww's functionality.

Plugins are the primary extension mechanism in Floww. A plugin can register custom nodes, add UI panels, respond to workflow events, integrate with external services, or modify Floww's behavior in virtually any way the API permits.

Plugin Structure

A Floww plugin is a directory with a well-defined layout:

my-plugin/
  manifest.json       # Plugin metadata and configuration
  index.js            # Entry point (loaded by Floww)
  assets/             # Optional static assets (icons, images)
    icon.svg
  lib/                # Optional internal modules
    helpers.js
  README.md           # Optional documentation

At minimum, a plugin needs manifest.json and index.js. Everything else is optional.

The Plugin Manifest

The manifest.json file tells Floww about your plugin — what it's called, what permissions it needs, and where its code lives.

{
  "name": "floww-plugin-github",
  "version": "1.2.0",
  "displayName": "GitHub Integration",
  "description": "Adds GitHub nodes for issues, PRs, and repository management.",
  "author": {
    "name": "Your Name",
    "url": "https://github.com/yourname"
  },
  "license": "MIT",
  "entry": "index.js",
  "permissions": [
    "network",
    "variables:read",
    "nodes:register"
  ],
  "flowwVersion": ">=0.8.0",
  "repository": "https://github.com/yourname/floww-plugin-github"
}

Manifest fields

Field	Required	Description
`name`	Yes	Unique identifier. Must be lowercase, alphanumeric, hyphens only.
`version`	Yes	Semver version string.
`displayName`	No	Human-readable name shown in the UI.
`description`	No	One-line description.
`author`	No	Object with `name` and optional `url`.
`license`	No	SPDX license identifier.
`entry`	Yes	Relative path to the plugin's main JS file.
`permissions`	Yes	Array of permission strings (see below).
`flowwVersion`	No	Semver range of compatible Floww versions.
`repository`	No	URL to source repository.

Permissions

Plugins must explicitly declare the capabilities they need. Users are prompted to approve permissions when installing a plugin.

Permission	Grants access to
`network`	Make HTTP/HTTPS requests from node execution
`filesystem:read`	Read files from the local file system
`filesystem:write`	Write files to the local file system
`variables:read`	Read workflow variables
`variables:write`	Create or modify workflow variables
`nodes:register`	Register custom node types
`ui:panel`	Add custom UI panels to the interface
`clipboard`	Access the system clipboard

Principle of least privilege

Only request the permissions your plugin actually needs. Requesting filesystem:write when you only need network will reduce user trust and may cause your plugin to be flagged during the registry review process.

Lifecycle Hooks

Your plugin's entry file must export an object with lifecycle hook functions. Floww calls these at specific moments during the plugin's lifetime.

// index.js
module.exports = {
  /**
   * Called when the plugin is first loaded.
   * Use this to register nodes, set up event listeners,
   * and initialize state.
   */
  onLoad(floww) {
    console.log('Plugin loaded!');
    floww.events.on('workflow:started', this.handleStart);
  },

  /**
   * Called when the plugin is being unloaded.
   * Clean up listeners, close connections, free resources.
   */
  onUnload(floww) {
    floww.events.off('workflow:started', this.handleStart);
  },

  /**
   * Called when the plugin is activated after being disabled.
   * Re-register any dynamic features.
   */
  onActivate(floww) {
    console.log('Plugin activated');
  },

  /**
   * Called when the user disables the plugin (without uninstalling).
   * Temporarily remove features but preserve state.
   */
  onDeactivate(floww) {
    console.log('Plugin deactivated');
  },

  handleStart(event) {
    console.log(`Workflow "${event.workflowName}" started`);
  }
};

Hook	When it fires	Typical use
`onLoad(floww)`	Plugin is first loaded at startup or install	Register nodes, subscribe to events, initialize
`onUnload(floww)`	Plugin is being uninstalled	Clean up everything
`onActivate(floww)`	Plugin is re-enabled after being disabled	Re-register features
`onDeactivate(floww)`	User disables the plugin	Remove features, preserve state

Accessing the Floww API

Every lifecycle hook receives the floww API object. This is your gateway to all of Floww's capabilities. The API is organized into namespaces:

floww.canvas

Interact with the visual canvas — add nodes, pan, zoom, query positions.

// Add a node to the canvas at a specific position
const node = floww.canvas.addNode('http-request', { x: 200, y: 300 });

// Fit the viewport to show all nodes
floww.canvas.fitToView();

floww.nodes

// Register a custom node type
floww.nodes.register({
  type: 'github-issue',
  displayName: 'GitHub Issue',
  category: 'Integrations',
  inputs: [{ name: 'repo', type: 'string' }],
  outputs: [{ name: 'issues', type: 'array' }],
  execute: async (inputs, config, context) => {
    const response = await fetch(
      `https://api.github.com/repos/${inputs.repo}/issues`
    );
    return { issues: await response.json() };
  }
});

floww.events

Subscribe to and emit events across the system.

// Listen for any node execution error
floww.events.on('node:error', (event) => {
  console.error(`Node ${event.nodeId} failed:`, event.error.message);
});

// Emit a custom event for other plugins to consume
floww.events.emit('github:rate-limited', { retryAfter: 60 });

Full API reference

For complete method signatures and all available namespaces, see the API Reference.

Packaging

To distribute your plugin, package it as a .zip file with your plugin directory at the root:

floww-plugin-github.zip
  └── floww-plugin-github/
        ├── manifest.json
        ├── index.js
        └── assets/
              └── icon.svg

Versioning guidelines

Follow Semantic Versioning strictly.
Bump major when you change node port schemas (breaks existing workflows).
Bump minor when you add new nodes or features.
Bump patch for bug fixes and documentation changes.

Users can install plugins by opening the .zip file in Floww or by dropping the extracted directory into their plugins folder at ~/.floww/plugins/.

Publishing

The Floww community registry is the central place to share plugins with other users.

Submission process

Prepare — ensure your plugin has a complete manifest.json, a descriptive README, and an icon.
Test — run your plugin against the latest stable Floww release. Confirm all declared permissions are necessary.
Submit — use the floww publish CLI command or submit via the registry web interface.
Review — a community reviewer will check your plugin for security, quality, and policy compliance. This typically takes 1-3 business days.
Published — once approved, your plugin appears in the in-app plugin browser and the registry website.

Registry policies

Plugins must not contain obfuscated code, must not exfiltrate user data, and must clearly document what permissions they use and why. See the full contributing guidelines for details.