Flow builder plugin

medusa-flow-builder-plugin

Shopify-Flow-style visual workflow automation for Medusa v2.

• Draggable node editor in the admin dashboard — trigger → conditions → wait → actions.
• .flow file import and export that interchanges with Shopify Flow. Task IDs translate both directions.
• Extensible task registry — register your own triggers, conditions, and actions from your app with registerTask.
• Durable WAIT — resumptions survive restarts via a persisted pending-resumption table + 1-minute cron sweeper.
• Built-in task catalog — 15 triggers, 2 control nodes (wait, condition), 13 actions covering orders, customers, products, webhooks, Slack, Customer.io, and log output.

Status: alpha. API may change. Not yet published to npm — for now, consume via Medusa's local-package workflow (yalc-based).

Install

Once published to npm

yarn add medusa-flow-builder-plugin

Until then — local install via Medusa's plugin CLI

In the plugin repo:

1yarn install
2yarn build              # runs `medusa plugin:build` → writes .medusa/server + .medusa/admin
3yalc publish            # publishes to your local yalc store
4                        # (the official `medusa plugin:publish` is broken in @medusajs/cli@2.13.3
5                        # — TypeError: cmd is not a function. Raw `yalc publish` does the same job.)

In the consumer Medusa app:

1medusa plugin:add medusa-flow-builder-plugin
2# Adds `"medusa-flow-builder-plugin": "file:.yalc/medusa-flow-builder-plugin"` to package.json,
3# creates .yalc/medusa-flow-builder-plugin/, and writes yalc.lock.
4yarn install

Register in your app's medusa-config.ts:

1module.exports = defineConfig({
2  plugins: [
3    { resolve: "medusa-flow-builder-plugin" },
4  ],
5  // …
6})

Run the migration so the plugin's tables are created:

yarn medusa db:migrate

Open the admin dashboard → sidebar Extensions → Flow Builder.

New devs: see HANDOVER.md for an end-to-end setup walkthrough that assumes zero Medusa experience.

Built-in tasks

All action config fields support {{ payload.path.to.field }} template interpolation against the triggering event's payload.

Registering your own tasks

Create a file in your app that runs at boot time — a subscriber, a loader, or instrumentation.ts:

1// src/subscribers/register-flow-tasks.ts
2import { registerTask } from "medusa-flow-builder-plugin"
3
4registerTask({
5  task_id: "acme::subscription::pause",
6  task_version: "0.1",
7  task_type: "ACTION",
8  label: "Pause subscription",
9  description: "Pauses the subscription referenced by the payload.",
10  category: "Subscription",
11  config_fields: [
12    { id: "subscription_id", label: "Subscription ID", type: "text", required: true },
13    { id: "reason", label: "Reason", type: "text" },
14  ],
15  input_ports: [{ id: "input", label: "" }],
16  output_ports: [{ id: "output", label: "" }],
17  async execute(ctx, config) {
18    const subscriptionService = ctx.container.resolve("subscription_service")
19    await subscriptionService.pause(config.subscription_id, { reason: config.reason })
20    return { status: "success" }
21  },
22})
23
24// Medusa needs a default export for subscribers; a no-op works:
25export default async function noop() {}
26export const config = { event: "__boot__:noop" }

The task appears in the admin palette immediately. Re-registering the same task_id overrides the previous definition, including built-ins.

For custom triggers bound to events Medusa doesn't fire natively, register the trigger AND write a subscriber that forwards the event:

1import { registerTask, runFlowsForMedusaEvent } from "medusa-flow-builder-plugin"
2
3registerTask({
4  task_id: "acme::billing::invoice_issued",
5  task_version: "0.1",
6  task_type: "TRIGGER",
7  label: "Invoice issued",
8  description: "Fires when our billing service issues an invoice.",
9  category: "Trigger",
10  config_fields: [],
11  output_ports: [{ id: "output", label: "" }],
12  trigger: { medusa_event: "acme.invoice_issued", payload_shape: { invoice_id: "string", amount: "number" } },
13})
14
15// In a subscriber:
16export default async function ({ event: { data }, container }) {
17  await runFlowsForMedusaEvent("acme.invoice_issued", data, container)
18}
19export const config = { event: "acme.invoice_issued" }

The plugin already ships umbrella subscribers for the built-in triggers listed above.

.flow file import / export

The list page has an Import .flow button that accepts Shopify Flow exports. Shopify task_ids are translated to their Medusa equivalents on import (see src/modules/flow_builder/interop/shopify-map.ts). Unmapped tasks are preserved as-is with an "unsupported" note — flows still open in the editor; unmapped steps are skipped at runtime.

Each row in the list page has an Export .flow button. Exports include a matching SHA-256 prefix of the JSON body. Task IDs reverse-translate to Shopify identifiers where a mapping exists, so the file drops back into Shopify Flow cleanly.

Durable WAIT

When a run hits a flow::wait step, it writes a row to flow_builder_pending_resumption (flow_run_id, step_id, resume_at, next_payload, variables) and stops that branch. A cron job runs every minute, sweeps due resumptions, and re-enters the runner at the step downstream of the wait. Runs survive restarts.

Units supported: seconds, minutes, hours, days. Resolution is 1 minute; sub-minute waits will fire on the next cron tick.

Local development

Medusa's plugin workflow is yalc-based. Each consuming app gets a copy of the built plugin under its own .yalc/ directory, with a file: reference in package.json — no npm registry needed during development.

1git clone https://github.com/Rx-Ventures/medusa-flow-builder-plugin
2cd medusa-flow-builder-plugin
3yarn install
4yarn build                  # medusa plugin:build
5yalc publish                # publishes to ~/.yalc
6
7# In your Medusa app:
8medusa plugin:add medusa-flow-builder-plugin
9yarn install
10yarn dev

For the rapid edit-loop while developing the plugin:

yarn dev                    # medusa plugin:develop — watch + auto-republish

If you don't want the watcher, do it manually after each change:

yarn build && yalc push     # rebuild + push to every yalc consumer

Heads up: medusa plugin:publish from @medusajs/cli@2.13.3 errors with TypeError: cmd is not a function. As a workaround, run yarn build followed by raw yalc publish — same end result. The bug appears fixed in 2.14.x; we'll switch back to the official command once the consumer app upgrades.

Heads up #2: yalc push only copies plugin files into the consumer's .yalc/ directory — it does not re-resolve transitive dependencies. If you change the plugin's dependencies field, the consumer needs to re-fetch them:

1# in the consuming app:
2yalc update && yarn install --check-files

Publishing to npm (when ready)

1yarn build
2npm publish --access public   # or `npm publish` for a private/scoped package

The prepublishOnly script re-runs the build for you, so consumers always get the compiled output. Only the contents of the files whitelist (.medusa/server, .medusa/admin, package.json, README.md, LICENSE) end up in the published tarball — source src/ is not shipped.

Testing

yarn test:unit

The suite covers: condition evaluation, template interpolation, WAIT duration parsing, .flow import/export round-trip, the Shopify↔Medusa task translation, and the registerTask extensibility hook.

License

MIT © Rx-Ventures