Plugins
Extend Ventyd with side effects
Plugin Interface
Plugins let you respond to committed events with side effects like analytics, logging, and notifications.
interface Plugin {
onCommitted({
entityName: string;
entityId: string;
events: Event[];
state: any;
}): Promise<void>;
}import type { Plugin } from 'ventyd';
const myPlugin: Plugin = {
// ...
}How to Use
Add plugins when creating a repository:
const repository = createRepository(User, {
adapter,
plugins: [analyticsPlugin, auditPlugin]
});Plugins run after events are safely persisted to the database.
Examples
Here are common plugin patterns you can use as starting points:
Error Handling
Handle errors gracefully with onPluginError:
const repository = createRepository(User, {
adapter,
plugins: [myPlugin],
onPluginError: (error, plugin) => {
console.error('Plugin failed:', error);
// Don't throw - let other plugins continue
}
});Best Practices
✅ Do
- Handle errors gracefully (try/catch)
- Make operations idempotent
- Keep plugins fast (queue heavy work)
- Use provided data only
❌ Don't
- Don't throw errors
- Don't load other entities
- Don't perform heavy synchronous work
- Don't mutate shared state
Creating Custom Plugins
const customPlugin: Plugin = {
async onCommitted({ events }) {
try {
// Your logic here
await myService.process(events);
} catch (error) {
logger.error('Processing failed', error);
// Don't throw - handle gracefully
}
}
};Make sure to:
- Return a Promise
- Handle all errors
- Avoid blocking operations
- Keep it simple and focused