Quick Start
This guide will walk you through everything you need to define a minimal step, set up your Motia project, and run the Motia dev server – all in one go, using pnpm for package management.
Setup your project: Create a New Project Folder
Let's create a new Motia project in a dedicated folder. This is the recommended approach for keeping your projects organized.
Use npx
to run the project creation command directly:
- This will:
- Download and run the Motia CLI project creation tool
- Create a new project directory named
<your-project-name>
. - Set up a basic Motia project structure inside the new folder.
- Install necessary dependencies using pnpm within the project folder.
- Add a
dev
script to yourpackage.json
. - Include example steps to get you started.
Choosing a Project Name: Replace <your-project-name>
with your desired project folder name.
Alternative Templates: To see other templates, run: npx motia templates
(or motia templates
if you installed globally).
You should see a new folder created with the following files inside:
Minimal Step Example (Already Included!)
✨ Good News! If you used the automated project setup with the default
template (as recommended above), you can skip this step!
The default
template already includes example steps in the steps
folder, including addNumbers.step.js
(or similar, depending on the template). These pre-built steps are ready for you to explore and run.
If you chose not to use the template or want to create a step from scratch manually, follow these steps:
-
Create a
steps
folder in your project's root directory (if you haven't already). -
Create a new file named
addNumbers.step.js
(oraddNumbers.step.ts
for TypeScript) inside thesteps
folder.addNumbers.step.js -
Paste the following code into your
addNumbers.step.js
file:This minimal step listens for the event
"add-numbers"
and emits"numbers-added"
. It's a basic example to get you started.
Start Motia Development Server & Workbench
Now, let's start Motia and see your workflow in action!
-
Open your terminal in your Motia project's root directory (where your
package.json
file is located). -
Run the development server command: Use the
dev
script that was set up in yourpackage.json
:bash pnpm run dev
Motia will:
- Scan your
steps
folder for step definition files (.step.ts
,.step.js
,.step.py
,.step.rb
). - Register your Steps with the Motia runtime.
- Launch a development server and the Motia Workbench UI (typically at
http://localhost:3000
).
Changing the Port: To run the Workbench on a different port, use the
--port
option:pnpm run dev --port 3001
- Scan your
View your Flow in the Workbench
-
Open your browser and navigate to the Motia Workbench. By default, it's running at:
http://localhost:3000
orhttp://127.0.0.1:3000
. -
Locate your Flow in the Sidebar: On the left sidebar of the Workbench UI, you should see a list of Flows.
- For the default template: You'll find a flow named "default".
- For the
addNumbers.step.js
example: You'll find a flow named "numbers".
-
Select your Flow: Click on the flow name in the sidebar.
-
Observe the Visual Flow: You should now see a visual representation of your flow in the main panel. This is the Motia Workbench visualizing the steps and event flow within your application!
You can click and drag the nodes in the visual editor to rearrange them for better clarity. Explore the UI to familiarize yourself with the Workbench!
Test your step
You can test your step using the Motia CLI:
If you used the automated project setup with the default template, you can test your step by emitting the following event:
If you used the add number example, you can test your step by emitting the following event:
Motia will:
Emit a new event with the provided topic and message
The event manager will detect the new event and match it against your registered step
Execute your step with the provided input
Log the journey of the event, including the emitted numbers-added event