Learn about Motia's project structure, file organization, and automatic step discovery system for building scalable workflow applications.

Project Structure

Understanding how to organize your Motia project is crucial for building maintainable and scalable workflow applications. This guide covers the directory structure, file naming conventions, and Motia's automatic step discovery system.

Basic Project Structure

Here's what a typical Motia project looks like:

api-gateway.step.ts

data-processor_step.py

send-notification.step.js

send-notification.tsx

package.json

requirements.txt

tsconfig.json

types.d.ts

motia-workbench.json

config.yml

File Descriptions

File	Purpose	Type	Auto-Generated
`01-api-gateway.step.ts`	TypeScript API endpoint	User Code	-
`02-data-processor_step.py`	Python data processing	User Code	-
`03-send-notification.step.js`	JavaScript automation	User Code	-
`send-notification.tsx`	Optional UI override component	User Code	-
`package.json`	Node.js dependencies (if using JS/TS)	Config	-
`requirements.txt`	Python dependencies (if using Python)	Config	-
`tsconfig.json`	TypeScript config (if using TypeScript)	Config	-
`types.d.ts`	Type definitions for your project	Generated	✅ By TypeScript
`motia-workbench.json`	🤖 Visual workflow positioning	Generated	✅ By Motia
`config.yml`	Optional Motia configuration	Config	-

The steps/ directory is the heart of your Motia application - this is where all your workflow logic lives. Motia automatically discovers and registers any file following the naming pattern.

Location and nesting rules

The steps/ directory must live at the project root (e.g., my-motia-project/steps).
You can freely nest steps in subfolders under steps/ (e.g., steps/aaa/a1.step.ts, steps/bbb/ccc/c1_step.py).
Discovery is recursive inside steps/, so deeper folder structures for large apps are supported.

Automatic Step Discovery

Key Concept: Automatic Discovery

Motia will automatically discover and register any file that follows the .step. naming pattern as a workflow step. You don't need to manually register steps - just create a file with the right naming pattern and Motia will find it.

Discovery Rules

Motia scans your steps/ directory and automatically registers files as steps based on these rules:

File must contain .step. or _step. in the filename (e.g., my-task.step.ts, my_task_step.py)
File must export a config object defining the step configuration
File must export a handler function containing the step logic
File extension determines the runtime (.ts = TypeScript, .py = Python, .js = JavaScript)

When you run motia dev, Motia will:

Scan the steps/ directory recursively
Find all files matching *.step.*
Parse their config exports to understand step types and connections
Register them in the workflow engine
Make them available in the Workbench

File Naming Convention

Motia uses this specific pattern for automatic step discovery:

[prefix-]descriptive-name.step.[extension]

The .step. part in the filename is required - this is how Motia identifies which files are workflow steps during automatic discovery.

Supported Languages & Extensions

Language	Extension	Example Step File	Runtime
TypeScript	`.ts`	`user-registration.step.ts`	Node.js with TypeScript
Python	`.py`	`data-analysis_step.py`	Python interpreter
JavaScript	`.js`	`send-notification.step.js`	Node.js

Naming Examples by Step Type

Step Type	TypeScript	Python	JavaScript
API Endpoint	`01-auth-api.step.ts`	`01-auth-api_step.py` or `auth_api_step.py`	`01-auth-api.step.js`
Event Handler	`process-order.step.ts`	`process-order_step.py` or `process_order_step.py`	`process-order.step.js`
Cron Job	`daily-report.step.ts`	`daily-report_step.py` or `daily_report_step.py`	`daily-report.step.js`
Data Processing	`transform-data.step.ts`	`ml-analysis_step.py` or `ml_analysis_step.py`	`data-cleanup.step.js`

Step Organization Patterns

Sequential Flow Organization

Perfect for linear workflows where order matters:

01-api-start.step.ts

02-validate-data_step.py

03-process-payment.step.js

04-send-confirmation.step.ts

05-cleanup_step.py

Step	Language	Purpose
`01-api-start.step.ts`	TypeScript	API endpoint
`02-validate-data_step.py`	Python	Data validation
`03-process-payment.step.js`	JavaScript	Payment processing
`04-send-confirmation.step.ts`	TypeScript	Email service
`05-cleanup_step.py`	Python	Cleanup tasks

Language-Specific Configuration

TypeScript/JavaScript Projects

For Node.js-based steps, you'll need:

package.json

{
  "name": "my-motia-app",
  "version": "1.0.0",
  "scripts": {
    "dev": "motia dev",
    "build": "motia build",
    "start": "motia start"
  },
  "dependencies": {
    "motia": "^0.5.12-beta.121",
    "zod": "^3.24.4"
  },
  "devDependencies": {
    "typescript": "^5.7.3",
    "@types/node": "^20.0.0"
  }
}

tsconfig.json (for TypeScript)

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "ESNext",
    "moduleResolution": "Node",
    "esModuleInterop": true,
    "strict": true,
    "skipLibCheck": true
  },
  "include": ["**/*.ts", "**/*.tsx"],
  "exclude": ["node_modules", "dist"]
}

Python Projects

For Python-based steps:

requirements.txt

# Core Motia dependency
motia>=0.5.12

# Common dependencies
requests>=2.28.0
pydantic>=1.10.0

# Data processing (if needed)
pandas>=1.5.0
numpy>=1.21.0

Step Discovery Examples

Let's see how Motia discovers different step types:

Example 1: TypeScript API Step

steps/user-api.step.ts

import { ApiRouteConfig, Handlers } from 'motia'
import { z } from 'zod'
 
// Motia discovers this file because:
// 1. Filename contains '.step.'
// 2. Exports 'config' object
// 3. Has .ts extension -> uses TypeScript runtime
export const config: ApiRouteConfig = {
  type: 'api',
  name: 'user-api',
  path: '/users',
  method: 'GET',
  emits: ['users.fetched'],
  flows: ['user-management']
}
 
export const handler: Handlers['user-api'] = async (req, { emit }) => {
  await emit({
    topic: 'users.fetched', 
    data: { users: [] }
  })
  
  return {
    status: 200,
    body: { message: 'Users retrieved' }
  }
}

Example 2: Python Event Step

steps/data-processor_step.py

# Motia discovers this file because:
# 1. Filename contains '.step.'  
# 2. Exports 'config' dict
# 3. Has .py extension -> uses Python runtime
 
config = {
    "type": "event",
    "name": "data-processor",
    "description": "Process incoming data with Python",
    "subscribes": ["users.fetched"],
    "emits": ["data.processed"],
    "flows": ["user-management"]
}
 
async def handler(input_data, ctx):
    """Process the data"""
    processed_data = {
        "original": input_data,
        "processed_at": ctx.utils.dates.now().isoformat(),
        "count": len(input_data.get("users", []))
    }
    
    await ctx.emit({
        "topic": "data.processed",
        "data": processed_data
    })

Example 3: JavaScript Automation Step

steps/send-notifications.step.js

// Motia discovers this file because:
// 1. Filename contains '.step.'
// 2. Exports 'config' object  
// 3. Has .js extension -> uses Node.js runtime
 
export const config = {
  type: 'event',
  name: 'send-notifications',
  description: 'Send notifications via multiple channels',
  subscribes: ['data.processed'],
  emits: ['notifications.sent'],
  flows: ['user-management']
}
 
export const handler = async (input, { emit, logger }) => {
  logger.info('Sending notifications', { data: input })
  
  // Send email, SMS, push notifications, etc.
  const results = await Promise.all([
    sendEmail(input),
    sendSMS(input),
    sendPush(input)
  ])
  
  await emit({
    topic: 'notifications.sent',
    data: { 
      results,
      sent_at: new Date().toISOString() 
    }
  })
}
 
async function sendEmail(data) { /* implementation */ }
async function sendSMS(data) { /* implementation */ }  
async function sendPush(data) { /* implementation */ }

Auto-Generated Files

Some files in your Motia project are automatically generated:

types.d.ts - TypeScript generates this for type definitions
motia-workbench.json - Motia manages visual node positions in the Workbench

Discovery Troubleshooting

If Motia isn't discovering your steps:

Common Issues

Missing .step. (or _step for Python) in filename

❌ Won't be discovered:

user-handler.ts

data-processor.py

webhook.js

✅ Will be discovered:

user-handler.step.ts

data-processor_step.py

webhook.step.js

Discovery Verification

Check if your steps are discovered:

# Run Motia in development mode
motia dev
 
# Look step creation in your console console:
➜ [CREATED] Step (Cron) steps/petstore/state-audit-cron.step.ts created
➜ [CREATED] Step (Event) steps/petstore/process-food-order.step.ts created
➜ [CREATED] Step (Event) steps/petstore/notification.step.ts created
➜ [CREATED] Step (API) steps/petstore/api.step.ts created

Next Steps

Now that you understand how Motia discovers and organizes steps:

Learn about Core Concepts to understand how steps work together
Explore Defining Steps for detailed step creation
Check out Triggers for API, Event, and Cron steps

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

Project Structure

On this page