@ribbonflow/designer

The interactive flow builder — a Vue app for authoring ribbonflow diagrams. Place and move nodes and edges, edit labels, widths, source rates, capacities, rejection edges, particle sizes and split/combine transforms, set the frame aspect ratio, and preview live through the real renderer. Export/import a single flow or a flow-set.

Install and run

Install the Designer as a development dependency in the project that owns the flow files:

pnpm add -D @ribbonflow/designer

Add a script to that project's package.json:

{
  "scripts": {
    "designer": "ribbonflow-designer --flow-root ./slidev/flows --port 5177"
  }
}

Then run pnpm designer. The CLI prints the final local URL and absolute flow root. It listens on 127.0.0.1 by default, so it is not exposed to the local network.

CLI options

• --flow-root <directory>: directory containing nested sets or flat flow files. Equivalent environment variable: RIBBONFLOW_FLOW_ROOT.
• --port <number>: Vite port (default 5174). Equivalent environment variable: RIBBONFLOW_PORT.
• --host <hostname>: listening host (default 127.0.0.1). Equivalent environment variable: RIBBONFLOW_HOST.

CLI flags take precedence over environment variables. Relative flow roots are resolved from the directory where the command is run. The command fails before starting Vite if the root is missing, not a directory, or not readable and writable.

When no root is supplied, a source checkout uses the repository examples/ directory. An installed package uses ./examples in the consuming project's working directory.

Persistence backends

The designer runs against either of two storage backends (spec §7.2):

• localStorage + download/upload (default) — zero-config, so the designer deploys as a plain static site anyone can host. pnpm --filter @ribbonflow/designer dev:local.
• Dev-server file API — reads/writes a directory of .flow.json files (the examples/ tree by default), for local authoring against version control. The ribbonflow-designer CLI and the repository dev script select this backend.

Nested layout

The existing ordered flow-set layout remains fully editable:

flows/
  onboarding/
    set.json
    opening.flow.json
    completed.flow.json

set.json supplies the set title, flow titles, order, and optional transition metadata. Creating, duplicating, renaming, deleting, and reordering flows works as before.

Flat layout

If the root contains direct *.flow.json files, the Designer presents them as one stable collection named Flows with id flat:

slidev/flows/
  opening.build-trap.flow.json
  opening.release.flow.json

The original basename is the stable flow id. Dots and other safe basename characters are preserved, and autosave writes back to the exact source file. The files are ordered by filename.

A flat collection has no set.json, and the Designer does not generate one. Existing files can be opened, edited, previewed, exported, and autosaved. Actions that require collection metadata or new filenames—create, duplicate, rename, delete, reorder, and transition editing—are unavailable in flat mode.

The flow root may contain nested sets and direct flat files at the same time, except that a nested set directory named flat conflicts with the reserved synthetic collection id.

Repository development

pnpm install
pnpm --filter @ribbonflow/designer dev      # → http://127.0.0.1:5174
pnpm --filter @ribbonflow/designer dev:local

Build the static app:

pnpm --filter @ribbonflow/designer build    # → designer/dist/

Tests

pnpm --filter @ribbonflow/designer test           # node:test unit suites
pnpm --filter @ribbonflow/designer test:e2e       # Playwright, server backend
pnpm --filter @ribbonflow/designer test:e2e:local # Playwright, localStorage backend

The unit suite includes external-root persistence and package installation smoke coverage. The package contains its CLI, Vite app source and configuration, and server-side file store; consumers do not need a Ribbonflow repository checkout.

Publish

Publish compatible versions of @ribbonflow/core and ribbonflow first. pnpm rewrites their workspace:* dependency ranges to released versions while packing the Designer.

Verify and publish the public package:

pnpm --filter @ribbonflow/designer test
pnpm --filter @ribbonflow/designer pack
pnpm --filter @ribbonflow/designer publish --access public

Live preview renders through ribbonflow; the inspector geometry comes from @ribbonflow/core.

License

MIT