Skip to content

Commit f5be430

Browse files
rohitg00rohitg00
authored
chore(docs): add plugins contribution guidelines & adapters section to README (#1009)
1 parent 1e928a8 commit f5be430

File tree

2 files changed

+198
-51
lines changed

2 files changed

+198
-51
lines changed

‎README.md‎

Lines changed: 41 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -244,19 +244,56 @@ The guides include patterns for API endpoints, background tasks, state managemen
244244

245245
> 🤖 **[Learn more about AI development support →](https://motia.dev/docs/ai-development-guide)**
246246
247-
## 🎯 Step Types
247+
## 🎯 Triggers
248248

249-
| Type | Trigger | Use Case |
250-
|------|---------|----------|
249+
| Type | When it runs | Use Case |
250+
|------|--------------|----------|
251251
| **`api`** | HTTP Request | REST endpoints |
252252
| **`event`** | Topic subscription | Background processing |
253253
| **`cron`** | Schedule | Recurring jobs |
254-
| **`noop`** | Manual | External processes |
255254

256255
> 📖 **[Learn more about Steps →](https://motia.dev/docs/concepts/steps)**
257256
258257
---
259258

259+
## 🔌 Plugins & Adapters
260+
261+
Extend Motia with plugins and customize infrastructure with adapters.
262+
263+
### Official Plugins
264+
265+
Pre-installed with every Motia project to enhance your workbench:
266+
267+
| Plugin | Description | NPM |
268+
|--------|-------------|-----|
269+
| **[@motiadev/plugin-logs](https://github.com/motiadev/motia/tree/main/plugins/plugin-logs)** | Real-time log viewer with filtering and search | [![npm](https://img.shields.io/npm/v/@motiadev/plugin-logs?style=flat&color=CB3837)](https://www.npmjs.com/package/@motiadev/plugin-logs) |
270+
| **[@motiadev/plugin-endpoint](https://github.com/motiadev/motia/tree/main/plugins/plugin-endpoint)** | Interactive API endpoint testing tool | [![npm](https://img.shields.io/npm/v/@motiadev/plugin-endpoint?style=flat&color=CB3837)](https://www.npmjs.com/package/@motiadev/plugin-endpoint) |
271+
| **[@motiadev/plugin-observability](https://github.com/motiadev/motia/tree/main/plugins/plugin-observability)** | Performance tracing and distributed monitoring | [![npm](https://img.shields.io/npm/v/@motiadev/plugin-observability?style=flat&color=CB3837)](https://www.npmjs.com/package/@motiadev/plugin-observability) |
272+
| **[@motiadev/plugin-states](https://github.com/motiadev/motia/tree/main/plugins/plugin-states)** | State management and inspection tool | [![npm](https://img.shields.io/npm/v/@motiadev/plugin-states?style=flat&color=CB3837)](https://www.npmjs.com/package/@motiadev/plugin-states) |
273+
| **[@motiadev/plugin-bullmq](https://github.com/motiadev/motia/tree/main/plugins/plugin-bullmq)** | BullMQ queue and DLQ management | [![npm](https://img.shields.io/npm/v/@motiadev/plugin-bullmq?style=flat&color=CB3837)](https://www.npmjs.com/package/@motiadev/plugin-bullmq) |
274+
275+
**[View all community plugins →](https://github.com/MotiaDev/awesome-plugins)**
276+
277+
### Official Adapters
278+
279+
Customize your infrastructure with production-ready adapters:
280+
281+
| Adapter | Purpose | NPM |
282+
|---------|---------|-----|
283+
| **[@motiadev/adapter-bullmq-events](https://github.com/motiadev/motia/tree/main/packages/adapter-bullmq-events)** | BullMQ-based event processing | [![npm](https://img.shields.io/npm/v/@motiadev/adapter-bullmq-events?style=flat&color=CB3837)](https://www.npmjs.com/package/@motiadev/adapter-bullmq-events) |
284+
| **[@motiadev/adapter-rabbitmq-events](https://github.com/motiadev/motia/tree/main/packages/adapter-rabbitmq-events)** | RabbitMQ event adapter | [![npm](https://img.shields.io/npm/v/@motiadev/adapter-rabbitmq-events?style=flat&color=CB3837)](https://www.npmjs.com/package/@motiadev/adapter-rabbitmq-events) |
285+
| **[@motiadev/adapter-redis-cron](https://github.com/motiadev/motia/tree/main/packages/adapter-redis-cron)** | Redis-based cron scheduling | [![npm](https://img.shields.io/npm/v/@motiadev/adapter-redis-cron?style=flat&color=CB3837)](https://www.npmjs.com/package/@motiadev/adapter-redis-cron) |
286+
| **[@motiadev/adapter-redis-state](https://github.com/motiadev/motia/tree/main/packages/adapter-redis-state)** | Redis state management | [![npm](https://img.shields.io/npm/v/@motiadev/adapter-redis-state?style=flat&color=CB3837)](https://www.npmjs.com/package/@motiadev/adapter-redis-state) |
287+
| **[@motiadev/adapter-redis-streams](https://github.com/motiadev/motia/tree/main/packages/adapter-redis-streams)** | Redis Streams for real-time data | [![npm](https://img.shields.io/npm/v/@motiadev/adapter-redis-streams?style=flat&color=CB3837)](https://www.npmjs.com/package/@motiadev/adapter-redis-streams) |
288+
289+
### Create Your Own
290+
291+
- **[Create a Plugin](https://github.com/MotiaDev/awesome-plugins/blob/main/CONTRIBUTING.md)** - Build custom workbench features
292+
- **[Plugin Development Guide](https://motia.dev/docs/development-guide/plugins)** - Complete documentation
293+
- **[Contribute to awesome-plugins](https://github.com/MotiaDev/awesome-plugins)** - Share with the community
294+
295+
---
296+
260297
## 🎯 Examples
261298

262299
### 🏆 **[ChessArena.ai](https://chessarena.ai)** - Full-Featured Production App

‎packages/docs/content/docs/development-guide/plugins.mdx‎

Lines changed: 157 additions & 47 deletions
Original file line numberDiff line numberDiff line change
@@ -99,7 +99,7 @@ type MotiaPluginContext = {
9999
100100
<Callout type="success" title="What the CLI template includes">
101101
- TypeScript and React configuration
102-
- Vite build setup
102+
- tsdown for fast, performant builds with React Compiler and Tailwind CSS v4
103103
- Example workbench UI component
104104
- Required dependencies pre-installed
105105
- Ready-to-build project structure
@@ -126,7 +126,7 @@ If you prefer to set up manually or want to understand the structure, follow the
126126
</Folder>
127127
<File name="package.json">Project metadata</File>
128128
<File name="tsconfig.json">TypeScript configuration</File>
129-
<File name="vite.config.ts">Vite build configuration</File>
129+
<File name="tsdown.config.ts">tsdown build/bundle configuration</File>
130130
<File name="postcss.config.js">PostCSS configuration</File>
131131
<File name="README.md">Plugin documentation</File>
132132
</Folder>
@@ -139,26 +139,49 @@ If you prefer to set up manually or want to understand the structure, follow the
139139
```json
140140
{
141141
"name": "@motiadev/plugin-example",
142-
"version": "0.8.2-beta.139",
142+
"version": "0.14.0-beta.164",
143143
"type": "module",
144144
"main": "./dist/index.js",
145145
"types": "./dist/index.d.ts",
146146
"exports": {
147147
".": {
148-
"types": "./dist/index.d.ts",
149-
"import": "./dist/index.js",
150-
"require": "./dist/index.cjs"
148+
"development": "./src/index.ts",
149+
"default": "./dist/index.js"
151150
},
152151
"./plugin": {
153-
"types": "./dist/plugin.d.ts",
154-
"import": "./dist/plugin.js",
155-
"require": "./dist/plugin.cjs"
152+
"development": "./src/plugin.ts",
153+
"default": "./dist/plugin.js"
156154
},
157-
"./styles.css": "./dist/styles.css"
155+
"./package.json": "./package.json"
158156
},
157+
"files": ["dist"],
159158
"peerDependencies": {
160-
"@motiadev/ui": "workspace:*",
161-
"@motiadev/core": "workspace:*"
159+
"@motiadev/core": "latest",
160+
"@motiadev/ui": "latest"
161+
},
162+
"dependencies": {
163+
"lucide-react": "^0.555.0",
164+
"react": "^19.2.0"
165+
},
166+
"devDependencies": {
167+
"@rollup/plugin-babel": "^6.1.0",
168+
"@tailwindcss/postcss": "^4.1.17",
169+
"rollup-plugin-postcss": "^4.0.2",
170+
"@types/node": "^24.10.1",
171+
"@types/react": "^19.2.7",
172+
"babel-plugin-react-compiler": "^1.0.0",
173+
"publint": "^0.3.15",
174+
"tailwindcss": "^4.1.17",
175+
"tsdown": "^0.16.8",
176+
"typescript": "^5.9.3",
177+
"unplugin-unused": "^0.5.6"
178+
},
179+
"publishConfig": {
180+
"exports": {
181+
".": "./dist/index.js",
182+
"./plugin": "./dist/plugin.js",
183+
"./package.json": "./package.json"
184+
}
162185
}
163186
}
164187
```
@@ -169,12 +192,12 @@ If you prefer to set up manually or want to understand the structure, follow the
169192
```typescript
170193
import type { MotiaPlugin, MotiaPluginContext } from '@motiadev/core'
171194

172-
export default function plugin(motia: MotiaPluginContext): MotiaPlugin {
195+
export default function plugin(_motia: MotiaPluginContext): MotiaPlugin {
173196
return {
174197
workbench: [
175198
{
176199
packageName: '@motiadev/plugin-example',
177-
cssImports: ['@motiadev/plugin-example/dist/plugin-example.css'],
200+
cssImports: ['@motiadev/plugin-example/dist/styles.css'],
178201
label: 'Example',
179202
position: 'bottom',
180203
componentName: 'ExamplePage',
@@ -189,7 +212,7 @@ If you prefer to set up manually or want to understand the structure, follow the
189212
Create your React component in `src/components/example-page.tsx`:
190213

191214
```typescript
192-
import { Badge, Button, Card } from '@motiadev/ui'
215+
import { Badge, Button } from '@motiadev/ui'
193216
import { Sparkles } from 'lucide-react'
194217
import type React from 'react'
195218

@@ -203,12 +226,48 @@ If you prefer to set up manually or want to understand the structure, follow the
203226
<Badge variant="info">v1.0.0</Badge>
204227
</div>
205228

206-
<Card className="p-6">
207-
<h2 className="text-xl font-semibold mb-4">Welcome!</h2>
229+
<p className="text-muted-foreground text-lg">
230+
Welcome to the example plugin! This demonstrates the basic structure
231+
and functionality of a Motia plugin.
232+
</p>
233+
234+
<div className="p-6 space-y-4">
235+
<h2 className="text-xl font-semibold">What is this?</h2>
208236
<p className="text-muted-foreground">
209-
This is your custom plugin content.
237+
This is a minimal example plugin that shows how to create custom
238+
workbench tabs in Motia. Plugins can extend the Motia workbench
239+
with custom functionality, visualizations, and tools.
210240
</p>
211-
</Card>
241+
242+
<div className="grid grid-cols-1 md:grid-cols-3 gap-4 mt-6">
243+
<div className="p-4 border rounded-lg">
244+
<h3 className="font-semibold mb-2">Easy to Create</h3>
245+
<p className="text-sm text-muted-foreground">
246+
Build plugins with React, TypeScript, and Tailwind CSS
247+
</p>
248+
</div>
249+
<div className="p-4 border rounded-lg">
250+
<h3 className="font-semibold mb-2">Integrated</h3>
251+
<p className="text-sm text-muted-foreground">
252+
Seamlessly integrate with Motia's workbench UI
253+
</p>
254+
</div>
255+
<div className="p-4 border rounded-lg">
256+
<h3 className="font-semibold mb-2">Powerful</h3>
257+
<p className="text-sm text-muted-foreground">
258+
Access Motia's plugin context and APIs
259+
</p>
260+
</div>
261+
</div>
262+
263+
<div className="flex gap-2 mt-6">
264+
<Button variant="default">
265+
<Sparkles className="w-4 h-4" />
266+
Get Started
267+
</Button>
268+
<Button variant="outline">View Documentation</Button>
269+
</div>
270+
</div>
212271
</div>
213272
</div>
214273
)
@@ -233,34 +292,62 @@ If you prefer to set up manually or want to understand the structure, follow the
233292
```
234293
</Step>
235294
<Step title="Configure build tooling">
236-
**Vite configuration** — Create `vite.config.ts`:
295+
**tsdown configuration** — Create `tsdown.config.ts`:
237296
238297
```typescript
239-
import tailwindcss from '@tailwindcss/vite'
240-
import react from '@vitejs/plugin-react'
241-
import { resolve } from 'path'
242-
import { defineConfig } from 'vite'
243-
import dts from 'vite-plugin-dts'
244-
245-
export default defineConfig({
246-
plugins: [react(), tailwindcss(), dts({ insertTypesEntry: true })],
247-
build: {
248-
lib: {
249-
entry: {
250-
index: resolve(__dirname, 'src/index.ts'),
251-
plugin: resolve(__dirname, 'src/plugin.ts'),
252-
},
253-
name: 'MotiaPluginExample',
254-
formats: ['es', 'cjs'],
255-
fileName: (format, entryName) =>
256-
`${entryName}.${format === 'es' ? 'js' : 'cjs'}`,
298+
import pluginBabel from '@rollup/plugin-babel'
299+
import postcss from 'rollup-plugin-postcss'
300+
import { defineConfig } from 'tsdown'
301+
302+
export default defineConfig([
303+
// Main JavaScript/TypeScript build
304+
{
305+
entry: {
306+
index: './src/index.ts',
307+
plugin: './src/plugin.ts',
308+
},
309+
format: 'esm',
310+
platform: 'browser',
311+
external: [/^react($|\/)/, 'react/jsx-runtime'],
312+
dts: {
313+
build: true,
257314
},
258-
rollupOptions: {
259-
external: ['react', 'react-dom', '@motiadev/core', '@motiadev/ui'],
315+
exports: {
316+
devExports: 'development',
260317
},
261-
cssCodeSplit: false,
318+
clean: true,
319+
publint: true,
320+
unused: true,
321+
outDir: 'dist',
322+
plugins: [
323+
pluginBabel({
324+
babelHelpers: 'bundled',
325+
parserOpts: {
326+
sourceType: 'module',
327+
plugins: ['jsx', 'typescript'],
328+
},
329+
plugins: ['babel-plugin-react-compiler'],
330+
extensions: ['.js', '.jsx', '.ts', '.tsx'],
331+
}),
332+
],
262333
},
263-
})
334+
// Separate CSS build
335+
{
336+
entry: {
337+
styles: './src/styles.css',
338+
},
339+
format: 'esm',
340+
platform: 'browser',
341+
outDir: 'dist',
342+
clean: false,
343+
plugins: [
344+
postcss({
345+
extract: true,
346+
minimize: process.env.NODE_ENV === 'prod',
347+
}),
348+
],
349+
},
350+
])
264351
```
265352
266353
**PostCSS configuration** — Create `postcss.config.js`:
@@ -299,8 +386,8 @@ If you prefer to set up manually or want to understand the structure, follow the
299386
```json
300387
{
301388
"scripts": {
302-
"build": "vite build",
303-
"dev": "vite build --watch",
389+
"build": "tsdown",
390+
"dev": "tsdown --watch",
304391
"clean": "rm -rf dist"
305392
}
306393
}
@@ -604,21 +691,44 @@ Use it as a starting point for your own plugins.
604691
- Verify the `componentName` matches your exported component
605692
- Ensure the plugin is built (`pnpm run build`)
606693
- Check browser console for errors
694+
- Ensure tsdown and Babel plugins are installed
607695
</Callout>
608696
609697
<Callout type="warning" title="Styles not loading">
610698
- Verify CSS is imported in `src/index.ts`
611-
- Check that `styles.css` is exported in `package.json`
612-
- Ensure TailwindCSS is properly configured
613-
- Confirm that `cssImports` is defined in `src/plugin.ts` with the path to the built CSS file (e.g., `['@motiadev/plugin-example/dist/plugin-example.css']`)
699+
- Check that the CSS build is configured in `tsdown.config.ts`
700+
- Ensure TailwindCSS is properly configured in `postcss.config.js`
701+
- Confirm that `cssImports` is defined in `src/plugin.ts` with the correct path (e.g., `['@motiadev/plugin-example/dist/styles.css']`)
614702
</Callout>
615703
616704
<Callout type="default" title="Resolving type errors">
617705
- Make sure `@motiadev/core` and `@motiadev/ui` are listed in `peerDependencies`
618706
- Run `pnpm install` so TypeScript picks up the types
619707
- Confirm `declaration: true` is set in `tsconfig.json`
708+
- Check external dependencies are correctly configured in tsdown
709+
</Callout>
710+
711+
## Publishing and Contributing Plugins
712+
713+
Want to share your plugin with the Motia community?
714+
715+
<Callout type="info" title="Publish to NPM and contribute">
716+
If you've created a plugin and want to share it with the community:
717+
718+
1. **Publish to NPM** - Make your plugin available for everyone to install
719+
2. **Add to awesome-plugins** - Submit your plugin to our curated list
720+
721+
For complete instructions on creating, publishing, and contributing plugins, see the **[Plugin Contributing Guide](https://github.com/MotiaDev/awesome-plugins/blob/main/CONTRIBUTING.md)**.
722+
723+
The guide includes:
724+
- Step-by-step NPM publishing workflow
725+
- Best practices for plugin development
726+
- Submission format and guidelines
727+
- Troubleshooting common issues
620728
</Callout>
621729
622730
## Next Steps
623731
624732
- Explore the [plugin-logs source code](https://github.com/motiadev/motia/tree/main/plugins/plugin-logs) for a complete example
733+
- Check out the [awesome-plugins repository](https://github.com/MotiaDev/awesome-plugins) for community plugins
734+
- Read the [Plugin Contributing Guide](https://github.com/MotiaDev/awesome-plugins/blob/main/CONTRIBUTING.md) to publish your own

0 commit comments

Comments
 (0)