Quick Start

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.

npx motia@latest create -n <your-project-name>

Minimal Step Example

The initial project comes with sample steps, but in this step we're going to walk you through on creating a new one

1. Create a new file named hello-world.step.js (or hello-world.step.ts for TypeScript) inside the steps folder.

   steps

   hello-world.step.js

2. Paste the following code into your hello-world.step.js file:

   exports.config = {
     type: 'api', // "event", "api", or "cron"
     path: '/hello-world',
     method: 'GET',
     name: 'HelloWorld',
     emits: [],
     flows: ['HelloWorld'],
   }
    
   exports.handler = async () => {
     return {
       status: 200,
       body: { message: 'Hello World' },
     }
   }

   This minimal API step creates a GET endpoint on /hello-world that returns a JSON

   { "message": "Hello World" }

Start Motia Development Server & Workbench

Now, let's start Motia and see your workflow in action!

1. Open your terminal in your Motia project's root directory (where your package.json file is located).

2. Run the development server command: Use the dev script that was set up in your package.json:

   npmyarnpnpmbun

   npm 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

1. 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.

2. 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 hello-world.step.js example: You'll find a flow named "HelloWorld".

3. Select your Flow: Click on the flow name in the sidebar.

4. 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

Now you created the step hello-world.js, which creates a GET /hello-world endpoint, you can test by either opening http://localhost:3000/hello-world or

curl http://localhost:3000/hello-world

This is a really simple example where you can have your first step running.

Understanding a flow with events

Now you already created an API Steps, let's check the flow that's already in the project, click on default flow on Workbench sidebar on the left. (Or navigate to http://localhost:3000/flow/default)

You should see the page below

This flow is a little bit more advanced, it has Noop steps (which we are going to talk about later), API steps, and Event steps.

Event steps are code that can take some time to finish and can have errors (like LLM calls which are non-deterministic), in case they fail, they can rerun later.

In the flow represented by the image above you should see a node with a button to start it, go ahead an click it and check the logs that are generated.

Now let's dive deep on the flow you already executed. Let's jump in to Core concepts