frameworks/motia/contributors/rfc/2025-07-31-motia-tutorial.md
This RFC proposes creating a tutorial for Motia that will help users understand how to use Motia's ecosystem (framework, workbench, cloud). It is aimed to be supplemental to the existing documentation and provide a more hands-on approach to learning Motia.
Currently, the learning curve for Motia is high due to the constant evolution of the Motia ecosystem. Most developers come with a background of what they would expect Motia does, depending on the marketing material they have seen and how they associate it to other products.
The main root causes that this RFC addresses are:
motia create cli commandsequenceDiagram
Developer->>+Motia CLI: `npx motia@latest create`
Motia CLI->>+Developer: Do you wish to learn how to use Motia through a tutorial? Y/N
Developer-->>-Motia CLI: Y
Motia CLI-->>-Developer: open browser
Note left of Motia CLI: create project with flow templates
for tutorial and open browser with workbench
Motia CLI-->>+Workbench: open workbench with first templatate of the tutorial
rect rgb(42, 126, 254)
loop Motia Tutorial
Workbench-->>+Developer: tutorial step
rect rgb(62, 204, 84, 0.8)
break tutorial ends
Workbench-->Developer: tutorial completed
end
end
Developer-->>-Workbench: next step
end
end
Analytics Data Flow
sequenceDiagram
box rgb(42, 126, 254) Workbench
Participant Tutorial
Participant Developer
end
loop Motia Tutorial
Tutorial-->>+Developer: tutorial step
Tutorial-->>+Amplitude: report developer journey
Note right of Tutorial: by reporting the developer journey
through the tutorial we can identify success and drop-off's
rect rgb(62, 204, 84, 0.8)
break tutorial ends
Tutorial-->Developer: tutorial completed
end
end
Developer-->>-Tutorial: next step
end
These type definitions are defined based on the assumption that driver.js will be used to implement the tutorial. These are not final and are subject to change, based on the final library used to implement the tutorial.
type TutorialStep = {
id: string
title: string
description?: string
position: 'left' | 'right' | 'top' | 'bottom'
elementId: string
segmentId: string
}
type TutorialSegment = {
id: string
title: string
description?: string
steps: TutorialStep[]
}
type TutorialConfig = {
initialSegmentId?: string
initialStepId?: string
}
The tutorial will be injected into workbench as an SDK (third party plugin), that will orchestrate the tutorial steps and report the developer journey to amplitude. The SDK will be agnostic of Workbench component structure, it will focus on orchestrating the tutorial steps through specific element identifiers.
interface MotiaTutorialSDK {
init: (config?: TutorialConfig) => void
currentStep: TutorialStep
currentStepIndex: number
currentSegment: TutorialSegment
nextStep: () => void
previousStep: () => void
jumpToStep: (stepId: string) => void
jumpToSegment: (segmentId: string) => void
abort: () => void
trackEvent: (event: string, context?: Record<string, unknown>) => void
}
The following is an example from driver.js, the final layout would be similar but themed to match Motia's design language.
The tutorial configuration will be maanaged internally, the following configuration can be provided to the SDK:
| Config Name | Description |
|---|---|
| initialSegmentId | The id of the segment to start the tutorial from |
| initialStepId | The id of the step to start the tutorial from |
The following env variables can be defined to override specific features from the tutorial:
| Env Variable | Description |
|---|---|
| MOTIA_DISABLE_TUTORIAL | This will disable the tutorial from being shown, and the tutorial question in the create command |
| MOTIA_ANALYTICS_DISABLED | This will disable the analytics reporting from the tutorial |
| MOTIA_SKIP_TUTORIAL | This will skip presenting the tutorial to a user if the response is N in the create command, this will be set as part of the create boilerplate |
> npx motia@latest create
> Do you wish to learn how to use Motia through a tutorial? Y/N
> Y
> ... rest of the create process
> Your project is ready, you will be redirect to Motia Workbench to start the tutorial
No performace impacts are identified, given that the tutorial will be agnostic of the inner workings of Workbench, it will have dependencies on specific element identifiers to navigate through the UI, but the performance of loading Workbench should not be affected.
Even if the tutorial grows in complexity, given its nature of a step by step guide, it reduces the impact on performance.
N/A
This proposal is important for Motia and its users (developers) because it will provide a hands-on experience for developers to learn how to use Motia's ecosystem, through a step by step guide that outlines a selection of templates that demonstrate how to use Motia's primitives and tools.