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:

npx motia create -t default -n <your-project-name>

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 your package.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:

one.step.ts

two.step.ts

api.step.ts

package.json

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 (or addNumbers.step.ts for TypeScript) inside the steps folder.

addNumbers.step.js

Paste the following code into your addNumbers.step.js file:

exports.config = {
  type: 'event', // "event", "api", or "cron"
  name: 'AddNumbers',
  subscribes: ['add-numbers'],
  emits: ['numbers-added'],
  flows: ['numbers'],
}
 
exports.handler = async (input, { emit }) => {
  const sum = (input.a || 0) + (input.b || 0)
  await emit({
    topic: 'numbers-added',
    data: { result: sum },
  })
}

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 your package.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

View your Flow in the Workbench

Open your browser and navigate to the Motia Workbench. By default, it's running at: http://localhost:3000 or http://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:

npx motia emit --topic test-state --message '{}'

If you used the add number example, you can test your step by emitting the following event:

npx motia emit --topic add-numbers --message '{"a": 5, "b": 3}'

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

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

Setup your project: Create a New Project Folder

Minimal Step Example (Already Included!)

Start Motia Development Server & Workbench

View your Flow in the Workbench

Test your step

On this page