Files

gsxdsm 0a418e6875 FN-5844: add plugin dev loop and external authoring docs

Add a local plugin development loop plus publishable external plugin guidance.

- add `fn plugin dev` routing and implementation with supervised build, install, and hot-reload behavior
- export plugin loader/store helpers and add CLI tests for dev flow, pack shape validation, and scaffold docs coverage
- document external plugin authoring, update CLI/plugin authoring docs, and add a patch changeset for `@runfusion/fusion`

Files changed:
 .changeset/fn-5844-external-plugin-authoring.md    |   5 +
 docs/PLUGIN_AUTHORING.md                           |  10 +-
 docs/cli-reference.md                              |   3 +-
 docs/plugins/external-authoring.md                 | 114 +++++++++++
 packages/cli/src/__tests__/bin.test.ts             |  16 +-
 packages/cli/src/__tests__/plugin-dev.test.ts      | 138 ++++++++++++++
 .../cli/src/__tests__/plugin-pack-shape.test.ts    |  94 +++++++++
 packages/cli/src/__tests__/plugin-scaffold.test.ts |   3 +
 packages/cli/src/bin.ts                            |  16 +-
 packages/cli/src/commands/plugin-dev.ts            | 212 +++++++++++++++++++++
 packages/cli/src/commands/plugin-scaffold.ts       |   6 +-
 packages/cli/src/commands/plugin.ts                |   6 +-
 12 files changed, 613 insertions(+), 10 deletions(-)

Fusion-Task-Id: FN-5844
Fusion-Task-Lineage: 80afa0a0-225c-486d-901a-909d14e7b056

2026-06-01 19:40:28 -07:00

2.9 KiB

Raw Blame History

External Plugin Authoring

This guide is for plugin authors using an installed @runfusion/fusion CLI. You do not need access to the Fusion monorepo.

Prerequisites

Node.js 18+
pnpm (or use the equivalent npm commands where noted)
An installed Fusion CLI available as fn

1. Scaffold a standalone plugin

fn plugin new my-plugin
cd my-plugin
pnpm install

The scaffold creates a standalone package named fusion-plugin-my-plugin. It depends on the published @runfusion/fusion package and imports SDK helpers from @runfusion/fusion/plugin-sdk; it must not contain private @fusion/* imports or workspace:* dependencies.

2. Develop locally with hot reload

Start Fusion locally, then run the plugin dev loop from the plugin directory:

fn plugin dev .

fn plugin dev .:

Runs the plugin build script (pnpm build, with npm run build fallback).
Resolves the compiled JavaScript entry from package.json exports/main or dist/index.js.
Reads and validates the root manifest.json.
Installs and enables the plugin into the local Fusion plugin store.
Watches src/ and, on save, rebuilds and hot-reloads with the Fusion plugin loader.

For a single CI-safe build/install/load pass without a watcher, use:

fn plugin dev . --once

You can also run the build yourself:

pnpm build

Troubleshooting: plugin entrypoints must be compiled JavaScript. fn plugin install and fn plugin dev reject .ts source entrypoints, so run the build before installing if you are not using the dev loop.

3. Test

pnpm test

If you prefer npm for a scaffold that supports it:

npm test

4. Package

Build first, then create an npm tarball:

pnpm build
pnpm pack

For my-plugin version 0.1.0, the tarball is named like:

fusion-plugin-my-plugin-0.1.0.tgz

The scaffolded package publishes only the files declared in package.json (dist, manifest.json, and package metadata) and exposes the plugin through:

{
  "exports": {
    ".": {
      "types": "./dist/index.d.ts",
      "import": "./dist/index.js"
    }
  }
}

Before sharing the tarball, confirm the artifact does not include private monorepo-only strings:

no @fusion/* imports or dependencies
no workspace:* dependency ranges
SDK imports come from @runfusion/fusion/plugin-sdk

5. Install elsewhere

On another machine with Fusion installed, extract or install the tarball, then point Fusion at the extracted plugin directory:

tar -xzf fusion-plugin-my-plugin-0.1.0.tgz
fn plugin install ./package
fn plugin enable fusion-plugin-my-plugin

If the plugin directory is already available, install it directly:

fn plugin install /path/to/fusion-plugin-my-plugin
fn plugin enable fusion-plugin-my-plugin

Use fn plugin list to confirm the plugin is installed and enabled for the current project.

2.9 KiB Raw Blame History