Plugin Architecture
Build self-contained feature modules that extend Recursiv
What is a Plugin?
A plugin is a self-contained feature module that extends Recursiv. Plugins follow the same architecture as core features — they’re just not bundled by default.
Plugins can:
- Add tRPC procedures (new API endpoints)
- Add database tables
- Add client-side screens and components
- Hook into existing features (posts, chat, agents)
Plugin Architecture
A plugin lives in packages/server/src/features/{plugin-name}/ and optionally packages/client/src/features/{plugin-name}/.
Server-Side Structure
Client-Side Structure (Optional)
Step-by-Step: Building a Plugin
1. Create the Feature Directory
2. Define the Database Schema
Add your tables to packages/server/src/db/schema.ts:
3. Create the Service
4. Create the Router
5. Create the Index
6. Register the Router
In packages/server/src/trpc/routers/index.ts:
7. Add Tests
Conventions
Naming
- Feature directory: lowercase, kebab-case (
rich-compose/) - Router file:
{name}.router.ts - Service file:
{Name}Service.ts(PascalCase) - Export:
{name}Router,{name}Service
Feature Gating
Use requireFeature() middleware so plugins can be toggled per tenant:
Network Isolation
Always filter by networkId from context:
Error Handling
Use TRPCError for client-facing errors:
Submitting Your Plugin
- Open a Plugin Proposal issue
- Get feedback from maintainers
- Build the plugin following this guide
- Submit a PR referencing the proposal issue
- Pass code review and CI
Plugin Review Criteria
- Follows the architecture patterns above
- Has tests (unit and/or integration)
- Uses feature gating (
requireFeature) - Scoped to network (
networkId) - No security vulnerabilities
- Clean TypeScript (passes
pnpm typecheck) - Documented (at minimum, JSDoc on public methods)
Revenue Sharing
Paid plugins in the marketplace generate revenue. Plugin authors receive a share of subscription revenue from their plugins. Details are arranged per-plugin — open a proposal issue to discuss.