Files

gsxdsm 601a85b7c9 FN-6474: clarify plugin tarball install docs

Clarifies packaged external plugin proof-point docs so tarballs are extracted before installation.

- Document that fn plugin install accepts built plugin directories or installed package names, not raw .tgz archives.
- Update external plugin proof-point and authoring guidance to extract pnpm pack output and install ./package.
- Add a static regression test guarding the runbook and authoring guide against raw tarball install instructions.

Files changed:
 docs/cli-reference.md                              |  1 +
 docs/plugins/external-authoring.md                 |  2 +-
 docs/plugins/external-proof-point-runbook.md       | 10 +++++-
 .../external-proof-point-runbook-install.test.ts   | 40 ++++++++++++++++++++++
 4 files changed, 51 insertions(+), 2 deletions(-)

Fusion-Task-Id: FN-6474

Fusion-Task-Lineage: 744d43ff-ed98-43a1-9cb9-e25f96225ab7

2026-06-16 15:08:24 -07:00

3.0 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. A raw *.tgz is not a valid fn plugin install argument; extract it first with tar -xzf and install from the unpacked ./package directory.

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.

3.0 KiB Raw Blame History