Flows

A Flow allows you to group steps, making it seamless to visually map out how events move through a sequence of steps. While flows are technically optional, they're invaluable for:

Clarity: Understand how steps interact with each other at a glance
Visualization: Get a visual representation of event flow across your steps
Observability: Group logs and events by flow name for easier debugging

Creating and Tagging Steps with a Flow

Flows are defined by tagging your steps with a flow name. Here's how to associate steps with a flow:

// addNumbers.step.js
exports.config = {
  type: 'event',
  name: 'AddNumbers',
  subscribes: ['add-numbers'],
  emits: ['numbers-added'],
  flows: ['calculator-flow'] // <-- Flow association
}
 
// ... handler definition

You can create complex workflows by connecting multiple steps within the same flow:

// validateNumbers.step.js
exports.config = {
  type: 'event',
  name: 'ValidateNumbers',
  subscribes: ['numbers-added'],
  emits: ['numbers-validated'],
  flows: ['calculator-flow'] // <-- Same flow name connects the steps
}
 
// ... handler definition

💡 Best Practices:

Use descriptive flow names that reflect their purpose (e.g., 'user-registration-flow', 'payment-processing-flow')
A step can belong to multiple flows: flows: ['billing-flow', 'analytics-flow']
Keep flows focused on specific business processes for better organization

Visualizing Your Flows

After you've defined your flows, you can visualize them in Motia Workbench.

Start your development server:

pnpm run dev

Open Motia Workbench in your browser (typically at http://localhost:3000 or http://127.0.0.1:3000). Flow Visualization in Workbench

Navigate to your flow name on the left sidebar and click it. You'll see a visual graph where each step is represented as a node, with connecting lines showing event flow patterns.

Click on any step node to inspect its configuration details, including name, emits, subscribes, and other properties.

Checkout the Motia Workbench docs for more information.

New to Motia? Follow the quick start guide to get set up.

Need help? See our Community Resources for questions, examples, and discussions.

Creating and Tagging Steps with a Flow

Visualizing Your Flows

On this page