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

user-handler.step.ts

email-service_step.py

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	-

Flexible Step Discovery

Motia automatically discovers and registers steps from both steps/ and src/ directories. You're not required to use a specific directory structure - organize your code however makes sense for your project!

Directory flexibility and organization

Both steps/ and src/ directories are supported - use whichever fits your team's conventions
Use one or both directories - mix and match based on your preferences
Recursive discovery - nest steps in subfolders as deeply as you need (e.g., steps/api/v1/users.step.ts, src/services/email/send_step.py)
No hierarchy or priority - both directories are treated equally
Organize freely - structure by feature, language, team, or any pattern that works for you

This means existing projects using steps/ continue to work, while new projects can use src/ or both directories together.

Automatic Step Discovery

Key Concept: Automatic Discovery

Motia automatically discovers and registers any file that follows the .step. naming pattern as a workflow step, regardless of where it's located in your steps/ or src/ directories. No manual registration required - just create a file with the right naming pattern and Motia will find it.

Discovery Rules

Motia scans your project and automatically registers files as steps based on these simple 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:

Recursively scan both steps/ and src/ directories (if they exist)
Find all files matching *.step.* or *_step.* patterns in either directory
Parse their config exports to understand step types and connections
Register them in the workflow engine
Make them available in the Workbench

No directory requirement - Steps are discoverable from anywhere within steps/ or src/, regardless of folder depth or organization pattern. Both directories are treated equally with no preference or priority.

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

All examples below can use either steps/ or src/ as the root directory - choose what works best for your team!

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