Build commands

Build commands compile your Motia application for production deployment with optimizations like bundling, minification, and tree-shaking.

motia build (JavaScript/TypeScript)

Creates an optimized production build of your project.

Usage

motia build [options]

Options

Option	Alias	Description	Default
`--external <packages>`	`-e`	Comma-separated list of external dependencies	`[]`

What it does

Bundles your code - Combines all steps and dependencies into a single file
Minifies output - Reduces file size for faster deployments
Tree-shakes unused code - Removes dead code to minimize bundle size
Generates source maps - Enables error tracking in production
Targets Node.js 22+ - Optimized for modern Node.js runtimes

Output

$ motia build

Building for production...
✓ dist/index-production.js [125.3 KB] (and 1 source map)

Done in 1.2s

The build creates:

dist/index-production.js - Minified production bundle
dist/index-production.js.map - Source map for debugging

Examples

Basic production build

motia build

Build with external dependencies

Keep certain packages external (not bundled):

motia build --external aws-sdk,@google-cloud/storage

This is useful when:

Deploying to environments that provide certain packages
Packages have native dependencies that shouldn’t be bundled
You want to reduce bundle size for packages available in the runtime

Build with environment variables

NODE_ENV=production motia build

motia build (Python)

Generates a production-ready Python entrypoint.

Usage

motia build [options]

Options

Option	Alias	Description	Default
`--dir <directory>`	`-d`	Directory containing step files	`steps`
`--verbose`	`-v`	Enable verbose logging	`false`

What it does

Discovers steps and streams - Finds all *_step.py and *_stream.py files
Generates index.py - Creates a production entrypoint at dist/index.py
Includes imports - Auto-imports all necessary Motia modules
Registers steps - Sets up step registration code

Output

$ motia build

2026-02-28 10:30:15 [INFO] motia.cli: Found 3 step(s) and 1 stream(s)
2026-02-28 10:30:15 [INFO] motia.cli: Build completed: dist/index.py

Generated entrypoint structure

The build command generates dist/index.py:

# Auto-generated by motia build
import asyncio
import importlib.util
import sys
from collections.abc import Mapping
from dotenv import load_dotenv
from motia.runtime import Motia
from motia.iii import get_instance

load_dotenv()

def load_module_from_path(path: str) -> None:
    spec = importlib.util.spec_from_file_location('step_module', path)
    if spec and spec.loader:
        module = importlib.util.module_from_spec(spec)
        sys.modules[f'step_module:{path}'] = module
        spec.loader.exec_module(module)

motia = Motia()

def load_and_register_step(path: str) -> None:
    spec = importlib.util.spec_from_file_location('step_module', path)
    if spec and spec.loader:
        module = importlib.util.module_from_spec(spec)
        sys.modules[f'step_module:{path}'] = module
        spec.loader.exec_module(module)
        config = getattr(module, 'config', None)
        handler = getattr(module, 'handler', None)
        if callable(handler) and (isinstance(config, Mapping) or hasattr(config, 'model_dump')):
            motia.add_step(config, path, handler)

def main() -> None:
    load_module_from_path(r'steps/user_stream.py')
    load_and_register_step(r'steps/send_message_step.py')
    load_and_register_step(r'steps/process_message_step.py')
    iii = get_instance()

    async def run() -> None:
        await iii.connect()
        while True:
            await asyncio.sleep(1)

    asyncio.run(run())

if __name__ == '__main__':
    main()

Running the production build

python dist/index.py

Or with the iii engine:

iii -c iii-config.yaml

Build optimization strategies

JavaScript/TypeScript

Minimize bundle size

Use external packages for large dependencies:

motia build --external aws-sdk,express,lodash

Tree-shake unused exports by using named imports:

// Good - tree-shakeable
import { someFunction } from 'library'

// Avoid - bundles entire library
import * as library from 'library'

Split large steps into smaller modules for better optimization.

Analyze bundle size

Check the build output for size information:

$ motia build

Building for production...
✓ dist/index-production.js [125.3 KB] (and 1 source map)

If the bundle is larger than expected:

Review dependencies in package.json
Use --external for packages provided by the runtime
Check for duplicate dependencies with npm ls

Python

Optimize imports

The generated dist/index.py only imports what’s needed. Keep your steps modular:

# Good - specific imports
from motia.runtime import Motia

# Avoid - imports unnecessary modules
import motia

Reduce file discovery

Specify the exact directory containing production steps:

motia build --dir src/steps/production

Deployment

JavaScript/TypeScript deployment

1. Build for production

motia build

2. Copy necessary files

cp iii-config.yaml dist/
cp .env.production dist/.env

3. Deploy the dist directory

Your deployment only needs:

dist/index-production.js
dist/index-production.js.map
iii-config.yaml
.env (environment-specific)

4. Run in production

iii -c iii-config.yaml

Python deployment

1. Build the entrypoint

motia build

2. Install dependencies

pip install -r requirements.txt

3. Copy step files

The production build references step files by path, so include them:

cp -r steps dist/

4. Deploy the dist directory

Your deployment needs:

dist/index.py
dist/steps/ (all step files)
iii-config.yaml
.env (environment-specific)
Python dependencies

5. Run in production

python dist/index.py

Or:

iii -c iii-config.yaml

Build configuration

esbuild settings (JavaScript/TypeScript)

The build uses these esbuild configurations:

{
  platform: 'node',      // Node.js runtime
  target: ['node22'],    // Modern Node.js features
  format: 'esm',         // ES modules
  bundle: true,          // Bundle dependencies
  minify: true,          // Minimize output
  sourcemap: true,       // Generate source maps
  treeShaking: true      // Remove unused code
}

Customizing builds

To customize the build process, you can create your own build script:

// custom-build.ts
import { build } from 'motia/build'

await build({
  external: ['aws-sdk', 'sharp'],
  // Additional esbuild options can be added in the future
})

Run it with:

tsx custom-build.ts

motia typegen (Production types)

Generate type definitions for production builds.

Usage

motia typegen --output dist/types.d.ts

For Python projects:

motia typegen --output schema.json

This creates a JSON schema manifest:

{
  "steps": [
    {
      "filePath": "steps/send_message_step.py",
      "config": {
        "name": "SendMessage",
        "triggers": [
          {
            "type": "http",
            "method": "POST",
            "path": "/messages"
          }
        ]
      }
    }
  ],
  "streams": []
}

Troubleshooting

Build fails with “Cannot find module”

Error: Cannot find module 'some-dependency'

Solution: Install missing dependencies:

npm install some-dependency

Bundle size too large

✓ dist/index-production.js [5.2 MB]

Solutions:

Use --external for large packages
Review and remove unused dependencies
Check for duplicate packages with npm dedupe

Python build missing steps

[INFO] motia.cli: Found 0 step(s) and 0 stream(s)

Solution: Check file naming - steps must end with _step.py:

# Correct
steps/example_step.py

# Incorrect - won't be discovered
steps/example.py
steps/exampleStep.py

Source maps not working in production

Ensure source maps are deployed alongside the bundle:

# Both files needed
dist/index-production.js
dist/index-production.js.map

Import errors in production

ERR_MODULE_NOT_FOUND: Cannot find package 'ws'

Solution: The ws package is always external. Install it in production:

npm install ws

Continuous Integration

GitHub Actions example

name: Build and Deploy

on:
  push:
    branches: [main]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '22'
      
      - name: Install dependencies
        run: npm ci
      
      - name: Build for production
        run: npm run build  # runs: motia build
      
      - name: Upload artifact
        uses: actions/upload-artifact@v3
        with:
          name: production-build
          path: dist/

Next steps

Deployment guide

Learn how to deploy your Motia application

Environment variables

Configure environment-specific settings

Monitoring

Monitor your production application

iii configuration

Optimize iii engine settings for production

TypeScript/JavaScript

Python

CLI

​motia build (JavaScript/TypeScript)

​Usage

​Options

​What it does

​Output

​Examples

​Basic production build

​Build with external dependencies

​Build with environment variables

​motia build (Python)

​Usage

​Options

​What it does

​Output

​Generated entrypoint structure

​Running the production build

​Build optimization strategies

​JavaScript/TypeScript

​Minimize bundle size

​Analyze bundle size

​Python

​Optimize imports

​Reduce file discovery

​Deployment

​JavaScript/TypeScript deployment

​1. Build for production

​2. Copy necessary files

​3. Deploy the dist directory

​4. Run in production

​Python deployment

​1. Build the entrypoint

​2. Install dependencies

​3. Copy step files

​4. Deploy the dist directory

​5. Run in production

​Build configuration

​esbuild settings (JavaScript/TypeScript)

​Customizing builds

​motia typegen (Production types)

​Usage

​Troubleshooting

​Build fails with “Cannot find module”

​Bundle size too large

​Python build missing steps

​Source maps not working in production

​Import errors in production

​Continuous Integration

​GitHub Actions example

​Next steps

Deployment guide

Environment variables

Monitoring

iii configuration

Build docs developers (and LLMs) love

motia build (JavaScript/TypeScript)

Usage

Options

What it does

Output

Examples

Basic production build

Build with external dependencies

Build with environment variables

motia build (Python)

Usage

Options

What it does

Output

Generated entrypoint structure

Running the production build

Build optimization strategies

JavaScript/TypeScript

Minimize bundle size

Analyze bundle size

Python

Optimize imports

Reduce file discovery

Deployment

JavaScript/TypeScript deployment

1. Build for production

2. Copy necessary files

3. Deploy the dist directory

4. Run in production

Python deployment

1. Build the entrypoint

2. Install dependencies

3. Copy step files

4. Deploy the dist directory

5. Run in production

Build configuration

esbuild settings (JavaScript/TypeScript)

Customizing builds

motia typegen (Production types)

Usage

Troubleshooting

Build fails with “Cannot find module”

Bundle size too large

Python build missing steps

Source maps not working in production

Import errors in production

Continuous Integration

GitHub Actions example

Next steps