Plugins

Plugins are a powerful way to extend Motia's functionality by adding custom features to the workbench, and integrating with external services.

What are Plugins?

Plugins in Motia allow you to:

Custom Workbench Tabs

Add custom tabs to the workbench interface

Specialized Visualizations

Create rich tooling tailored to your workflows

Service Integrations

Integrate with external services and APIs

Core Extensions

Extend Motia's core functionality with new capabilities

Reusable Modules

Share reusable functionality across projects

Motia comes with several official plugins like plugin-logs, plugin-endpoint, plugin-observability, plugin-states, ws-plugin, and cron-plugin that demonstrate the power and flexibility of the plugin system.

Plugin Architecture

Core Types

Plugins are built using three main TypeScript types:

MotiaPlugin

The main plugin configuration returned by your plugin function:

type MotiaPlugin = {
  workbench: WorkbenchPlugin[]  // Array of workbench tab configurations
  dirname?: string              // Optional plugin directory
  steps?: string[]              // Optional custom steps
}

WorkbenchPlugin

Configuration for a workbench tab:

type WorkbenchPlugin = {
  packageName: string           // Package registry name (e.g., '@motiadev/plugin-example')
  componentName?: string        // React component name to render
  label?: string                // Tab label text
  labelIcon?: string            // Icon name from lucide-react
  position?: 'bottom' | 'top'   // Tab position in workbench
  cssImports?: string[]         // CSS files to import
  props?: Record<string, any>   // Props passed to component
}

MotiaPluginContext

Context object provided to your plugin with access to Motia's internal APIs:

type MotiaPluginContext = {
  printer: Printer              // Logging utilities
  state: StateAdapter           // State management
  lockedData: LockedData        // Thread-safe data access
  tracerFactory: TracerFactory  // Tracing functionality
  registerApi: (...)            // Register custom API endpoints
}

Creating a Plugin

Quick Start with CLI

The fastest way to create a new plugin is using the Motia CLI:

pnpm dlx motia create --plugin my-plugin

After creation, set up and verify the build pipeline:

cd my-plugin
pnpm install
pnpm run build

What the CLI template includes

TypeScript and React configuration
tsdown for fast, performant builds with React Compiler and Tailwind CSS v4
Example workbench UI component
Required dependencies pre-installed
Ready-to-build project structure

Manual Setup

If you prefer to set up manually or want to understand the structure, follow these steps:

Create a new directory for your plugin with the following structure:

index.ts

plugin.ts

styles.css

package.json

tsconfig.json

tsdown.config.ts

postcss.config.js

README.md

Create a package.json with proper exports for both the main entry and plugin definition:

{
  "name": "@motiadev/plugin-example",
  "version": "0.1.0",
  "type": "module",
  "main": "./dist/index.js",
  "types": "./dist/index.d.ts",
  "exports": {
    ".": {
      "development": "./src/index.ts",
      "default": "./dist/index.js"
    },
    "./plugin": {
      "development": "./src/plugin.ts",
      "default": "./dist/plugin.js"
    },
    "./package.json": "./package.json"
  },
  "files": ["dist"],
  "peerDependencies": {
    "@motiadev/core": "latest",
    "@motiadev/ui": "latest"
  },
  "dependencies": {
    "lucide-react": "^0.555.0",
    "react": "^19.2.0"
  },
  "devDependencies": {
    "@rollup/plugin-babel": "^6.1.0",
    "@tailwindcss/postcss": "^4.1.17",
    "rollup-plugin-postcss": "^4.0.2",
    "@types/node": "^24.10.1",
    "@types/react": "^19.2.7",
    "babel-plugin-react-compiler": "^1.0.0",
    "publint": "^0.3.15",
    "tailwindcss": "^4.1.17",
    "tsdown": "^0.16.8",
    "typescript": "^5.9.3",
    "unplugin-unused": "^0.5.6"
  },
  "publishConfig": {
    "exports": {
      ".": "./dist/index.js",
      "./plugin": "./dist/plugin.js",
      "./package.json": "./package.json"
    }
  }
}

Create src/plugin.ts to define your plugin:

import type { MotiaPlugin, MotiaPluginContext } from '@motiadev/core'
 
export default function plugin(_motia: MotiaPluginContext): MotiaPlugin {
  return {
    workbench: [
      {
        packageName: '@motiadev/plugin-example',
        cssImports: ['@motiadev/plugin-example/dist/styles.css'],
        label: 'Example',
        position: 'bottom',
        componentName: 'ExamplePage',
        labelIcon: 'sparkles',
      },
    ],
  }
}

Create your React component in src/components/example-page.tsx:

import { Badge, Button } from '@motiadev/ui'
import { Sparkles } from 'lucide-react'
import type React from 'react'
 
export const ExamplePage: React.FC = () => {
  return (
    <div className="h-full w-full p-6 overflow-auto">
      <div className="max-w-4xl mx-auto space-y-6">
        <div className="flex items-center gap-3">
          <Sparkles className="w-8 h-8 text-primary" />
          <h1 className="text-3xl font-bold">Example Plugin</h1>
          <Badge variant="info">v1.0.0</Badge>
        </div>
 
        <p className="text-muted-foreground text-lg">
          Welcome to the example plugin! This demonstrates the basic structure 
          and functionality of a Motia plugin.
        </p>
 
        <div className="p-6 space-y-4">
          <h2 className="text-xl font-semibold">What is this?</h2>
          <p className="text-muted-foreground">
            This is a minimal example plugin that shows how to create custom 
            workbench tabs in Motia. Plugins can extend the Motia workbench 
            with custom functionality, visualizations, and tools.
          </p>
 
          <div className="grid grid-cols-1 md:grid-cols-3 gap-4 mt-6">
            <div className="p-4 border rounded-lg">
              <h3 className="font-semibold mb-2">Easy to Create</h3>
              <p className="text-sm text-muted-foreground">
                Build plugins with React, TypeScript, and Tailwind CSS
              </p>
            </div>
            <div className="p-4 border rounded-lg">
              <h3 className="font-semibold mb-2">Integrated</h3>
              <p className="text-sm text-muted-foreground">
                Seamlessly integrate with Motia's workbench UI
              </p>
            </div>
            <div className="p-4 border rounded-lg">
              <h3 className="font-semibold mb-2">Powerful</h3>
              <p className="text-sm text-muted-foreground">
                Access Motia's plugin context and APIs
              </p>
            </div>
          </div>
 
          <div className="flex gap-2 mt-6">
            <Button variant="default">
              <Sparkles className="w-4 h-4" />
              Get Started
            </Button>
            <Button variant="outline">View Documentation</Button>
          </div>
        </div>
      </div>
    </div>
  )
}

Create src/index.ts to export your components:

import './styles.css'
 
export { ExamplePage } from './components/example-page'

Create src/styles.css to import Motia's UI styles:

@import "@motiadev/ui/globals.css";
@import "tailwindcss";

tsdown configuration — Create tsdown.config.ts:

import pluginBabel from '@rollup/plugin-babel'
import postcss from 'rollup-plugin-postcss'
import { defineConfig } from 'tsdown'
 
export default defineConfig([
  // Main JavaScript/TypeScript build
  {
    entry: {
      index: './src/index.ts',
      plugin: './src/plugin.ts',
    },
    format: 'esm',
    platform: 'browser',
    external: [/^react($|\/)/, 'react/jsx-runtime'],
    dts: {
      build: true,
    },
    exports: {
      devExports: 'development',
    },
    clean: true,
    publint: true,
    unused: true,
    outDir: 'dist',
    plugins: [
      pluginBabel({
        babelHelpers: 'bundled',
        parserOpts: {
          sourceType: 'module',
          plugins: ['jsx', 'typescript'],
        },
        plugins: ['babel-plugin-react-compiler'],
        extensions: ['.js', '.jsx', '.ts', '.tsx'],
      }),
    ],
  },
  // Separate CSS build
  {
    entry: {
      styles: './src/styles.css',
    },
    format: 'esm',
    platform: 'browser',
    outDir: 'dist',
    clean: false,
    plugins: [
      postcss({
        extract: true,
        minimize: process.env.NODE_ENV === 'prod',
      }),
    ],
  },
])

PostCSS configuration — Create postcss.config.js:

export default {
  plugins: {
    '@tailwindcss/postcss': {},
  },
}

TypeScript configuration — Create tsconfig.json:

{
  "compilerOptions": {
    "target": "ES2020",
    "lib": ["ES2020", "DOM", "DOM.Iterable"],
    "module": "ESNext",
    "moduleResolution": "bundler",
    "jsx": "react-jsx",
    "strict": true,
    "declaration": true,
    "declarationMap": true,
    "sourceMap": true
  },
  "include": ["src"],
  "exclude": ["dist", "node_modules"]
}

Add build scripts to your package.json:

{
  "scripts": {
    "build": "tsdown",
    "dev": "tsdown --watch",
    "clean": "rm -rf dist"
  }
}

Then run the build:

pnpm run build

Local Plugins

Local plugins provide a simpler alternative to creating full distributable packages when you want to add custom functionality specific to your project. Unlike publishable plugins, local plugins don't require building, packaging, or separate dependencies—they live directly in your project directory.

When to Use Local Plugins

Local plugins are ideal for:

Development & prototyping

Quickly test plugin ideas without the overhead of package setup.

Project-specific features

Ship custom functionality that only matters for your project.

Internal tooling

Build dashboards, monitors, or utilities tailored to your team.

Learning environment

Understand how plugins work before creating a distributable package.

The `~/` Package Name Syntax

Local package resolution with ~/

The ~/ prefix in packageName tells Motia to load components from your local project directory instead of node_modules:

workbench: [
  {
    packageName: '~/plugins',  // Loads from <project-root>/plugins
    cssImports: ['~/plugins/dist/styles.css'], // Loads from <project-root>/plugins/dist/styles.css
    componentName: 'Plugin',
    // ...
  }
]

Motia resolves ~/ to your project root, so you can import components without publishing them as registry packages.

Creating a Local Plugin

Create a simple structure in your project:

index.tsx

motia.config.ts

In motia.config.ts, create a plugin function that returns the plugin configuration:

import path from 'node:path'
import { config, type MotiaPlugin, type MotiaPluginContext } from '@motiadev/core'
 
function localPluginExample(motia: MotiaPluginContext): MotiaPlugin {
  // Register custom API endpoint
  motia.registerApi(
    {
      method: 'GET',
      path: '/__motia/local-plugin-example',
    },
    async (req, ctx) => {
      return {
        status: 200,
        body: {
          message: 'Hello from Motia Plugin!',
          timestamp: new Date().toISOString(),
          environment: process.env.NODE_ENV || 'development',
          status: 'active',
        },
      }
    },
  )
 
  return {
    dirname: path.join(__dirname, 'plugins'),
    steps: ['**/*.step.ts', '**/*_step.py'],
    workbench: [
      {
        componentName: 'Plugin',
        packageName: '~/plugins',  // Load from local project
        label: 'Local Plugin Example',
        position: 'top',
        labelIcon: 'toy-brick',
      },
    ],
  }
}
 
export default config({
  plugins: [localPluginExample],
})

Create plugins/index.tsx with your component:

import { Badge, Button, cn } from '@motiadev/ui'
import { AlertCircle, CheckCircle2, Clock, RefreshCw, Server } from 'lucide-react'
import { useCallback, useEffect, useState } from 'react'
 
interface PluginData {
  message: string
  timestamp: string
  environment: string
  status: 'active' | 'inactive'
}
 
export const Plugin = () => {
  const [data, setData] = useState<PluginData | null>(null)
  const [isLoading, setIsLoading] = useState(true)
 
  const fetchData = useCallback(async () => {
    setIsLoading(true)
    try {
      const response = await fetch('/__motia/local-plugin-example')
      const result = await response.json()
      setData(result)
    } catch (err) {
      console.error('Failed to fetch data:', err)
    } finally {
      setIsLoading(false)
    }
  }, [])
 
  useEffect(() => {
    fetchData()
  }, [fetchData])
 
  return (
    <div className="h-full flex flex-col p-4 gap-4">
      <div className="flex items-center justify-between border-b pb-4">
        <div className="flex items-center gap-3">
          <Server className="w-5 h-5 text-accent-1000" />
          <h1 className="text-xl font-semibold">Local Plugin Example</h1>
        </div>
        <Button onClick={fetchData} disabled={isLoading}>
          <RefreshCw className={cn('w-4 h-4', isLoading && 'animate-spin')} />
          Refresh
        </Button>
      </div>
      
      {data && (
        <div className="space-y-4">
          <div className="p-4 rounded-lg border bg-card">
            <Badge variant={data.status === 'active' ? 'default' : 'secondary'}>
              {data.status}
            </Badge>
            <p className="text-2xl font-semibold mt-2">{data.message}</p>
          </div>
        </div>
      )}
    </div>
  )
}

Including Custom Steps

Include custom steps

Local plugins can also include custom steps by specifying a dirname and steps pattern:

return {
  dirname: path.join(__dirname, 'plugins'),
  steps: ['**/*.step.ts', '**/*_step.py'],
  workbench: [/* ... */],
}

This loads API routes, event handlers, and other step types directly from the plugin directory.

Note: Plugin steps follow the same discovery rules as regular steps - they can be organized in subdirectories and will be discovered recursively. The dirname specifies the root directory to scan, and steps can be nested at any depth within it.

Best Practices for Local Plugins

Keep components simple

Use Motia UI components directly without extra build tooling.

Use TypeScript

Leverage type safety and IDE support without extra declaration files.

Organize by feature

Group related components and steps inside meaningful folders.

Reuse dependencies

Rely on packages already present in your project workspace.

Document your APIs

Add clear comments for every custom endpoint and interface.

When to Migrate to NPM Plugin

When to publish as a distributable package

You want to share it across multiple projects
It provides general-purpose functionality
You need versioning and dependency management
The plugin is stable and well-tested

Using Plugins

Installing a Plugin

pnpm add @motiadev/plugin-example

import examplePlugin from '@motiadev/plugin-example/plugin'
 
export default {
  plugins: [examplePlugin],
}

Configuring Multiple Plugins

Configure multiple plugins

import logsPlugin from '@motiadev/plugin-logs/plugin'
import endpointPlugin from '@motiadev/plugin-endpoint/plugin'
import examplePlugin from '@motiadev/plugin-example/plugin'
 
export default {
  plugins: [
    logsPlugin,
    endpointPlugin,
    examplePlugin,
  ],
}

Registering Custom APIs

Use the registerApi method from the plugin context:

import { MotiaPlugin } from './app-config-types'
export default function plugin(motia: MotiaPluginContext): MotiaPlugin {
  // Register a custom API endpoint
  motia.registerApi(
    {
      method: 'GET',
      path: '/api/my-endpoint',
    },
    async (req, res) => {
      return res.json({ message: 'Hello from plugin!' })
    }
  )
 
  return {
    workbench: [/* ... */],
  }
}

Example Plugin

Example plugin reference

A complete minimal example plugin lives at plugins/plugin-example in the Motia repository. It demonstrates:

Basic plugin structure
Workbench tab integration
UI component creation
Build configuration
TypeScript setup

Use it as a starting point for your own plugins.

Troubleshooting

Plugin not showing in workbench

Check that the plugin is imported in motia.config.ts
Verify the componentName matches your exported component
Ensure the plugin is built (pnpm run build)
Check browser console for errors
Ensure tsdown and Babel plugins are installed

Styles not loading

Verify CSS is imported in src/index.ts
Check that the CSS build is configured in tsdown.config.ts
Ensure TailwindCSS is properly configured in postcss.config.js
Confirm that cssImports is defined in src/plugin.ts with the correct path (e.g., ['@motiadev/plugin-example/dist/styles.css'])

Resolving type errors

Make sure @motiadev/core and @motiadev/ui are listed in peerDependencies
Run pnpm install so TypeScript picks up the types
Confirm declaration: true is set in tsconfig.json
Check external dependencies are correctly configured in tsdown

Publishing and Contributing Plugins

Want to share your plugin with the Motia community?

Publish to NPM and contribute

If you've created a plugin and want to share it with the community:

Publish to NPM - Make your plugin available for everyone to install
Add to awesome-plugins - Submit your plugin to our curated list

For complete instructions on creating, publishing, and contributing plugins, see the Plugin Contributing Guide.

The guide includes:

Step-by-step NPM publishing workflow
Best practices for plugin development
Submission format and guidelines
Troubleshooting common issues

Next Steps

Explore the plugin-logs source code for a complete example
Check out the awesome-plugins repository for community plugins
Read the Plugin Contributing Guide to publish your own

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