Motia Icon
ConceptsSteps

Defining Steps

Steps are the fundamental building blocks in Motia that encapsulate isolated pieces of business logic.

Steps have two core behaviors:

  1. Event Subscription: Steps can subscribe to specific topics, allowing them to listen and react to particular events.
  2. Event Emission: Steps can emit new topics, triggering an event for other steps to react to.

Steps can operate in two different patterns:

  • Independent: Each step can function as a standalone unit, processing its logic in isolation.
  • Flow: Steps can be connected together in a sequence, creating a flow where the output of one step becomes the input for another.

This modular approach allows you to:

  • Build reusable components of business logic
  • Create complex workflows by combining simple steps
  • Maintain clear separation of concerns
  • Scale and modify parts of your system independently

Steps can be defined in any language that Motia supports, such as TypeScript, JavaScript, Python, and Ruby. Steps can be of type event, api, or cron. Steps are composed of a config object and a handler function.

Config

A step's configuration is defined through a config object that must be exported. This object contains essential properties that tell Motia how to interact with the step.

PropTypeDescription
string
The step type: event, api, or cron
string
A unique identifier for the step, used in Motia Workbench visualization tool
string[]
A list of topics this step listens to
string[]
A list of topics this step can emit
string[]
A list of flow identifiers that this step belongs to
string
Optional description for documentation and visualization

Each step type has its own set of properties, specific to that step type, which are described in the following sections.

Handler

A handler holds the business logic of a step. When an event occurs that matches the step's subscribed topics, the handler automatically runs with two key pieces of information:

  1. The input data from the triggering event
  2. A context object that provides useful tools:
    • emit: Sends new events to other steps
    • traceId: Helps track the flow of operations
    • state: Manages data persistence
    • logger: Records important information

Here're examples of how to define a handler in the Motia supported languages:

import { EventConfig, StepHandler } from 'motia'
 
export const config: EventConfig = {
  type: 'event',
  name: 'Minimal Step',
  subscribes: ['start'],
  emits: ['done'],
}
 
export const handler: StepHandler<typeof config> = async (input, { emit, traceId, state, logger }) => {
  await emit({ topic: 'done', data: {} })
}

Follow the quick start guide if you haven't set up Motia yet.

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

On this page