🧩 Runkun

A Universal React Plugin Runtime for Any Framework
通用的 React 插件运行时系统，让 React 插件能在任何框架中运行

🎯 What is Runkun?

Runkun is a framework-agnostic plugin runtime system that allows developers to:

• ✍️ Write Once, Run Anywhere: Write React plugins that work in any framework (Svelte, Vue, Angular, React, Native...)
• 🎨 Native Rendering: Use host application's native components for rendering
• 🚀 Framework Agnostic: Same React plugins work across different frameworks
• 🔒 Secure: Multiple isolation modes (Worker, Node.js, Main Thread)
• ⚡ Performance Optimized: Choose the right runtime mode for your use case

💡 Why Runkun?

Current Challenges

Plugin Developer 😰
├── Want to write plugins for Svelte app → Learn Svelte
├── Want to write plugins for Vue app → Learn Vue
├── Want to write plugins for Angular app → Learn Angular
└── Same functionality, written 3 times 😫

App Developer 😰
├── My app uses Svelte
├── But React has the largest plugin ecosystem
└── Can't leverage React ecosystem 😫

Runkun's Solution

Plugin Developer 😊
└── Only need to learn React + Runkun API → Plugin runs in any framework ✨

App Developer 😊
├── My app uses Svelte
├── Implement a Runkun Adapter
└── Immediately get access to entire React plugin ecosystem ✨

🏗️ Architecture

┌────────────────────────────────────────────────────────────┐
│                    Plugin Layer (React)                     │
│  - Plugin developers write React components                 │
│  - Import from @runkun/api (Button, Input, etc.)           │
└────────────────────────────────────────────────────────────┘
                            ↓
┌────────────────────────────────────────────────────────────┐
│                   Runtime Layer (Core)                      │
│  - Custom React Reconciler                                  │
│  - Component Tree Serialization                            │
│  - Event Handler Management                                │
└────────────────────────────────────────────────────────────┘
                            ↓
┌────────────────────────────────────────────────────────────┐
│                  Adapter Layer (Framework)                  │
│  - Svelte Adapter → Svelte Components                      │
│  - Vue Adapter → Vue Components (Coming Soon)              │
│  - Angular Adapter → Angular Components (Planned)          │
└────────────────────────────────────────────────────────────┘

🚀 Quick Start

For Plugin Developers

// 1. Install dependencies
pnpm add @runkun/api react

// 2. Create your plugin
import { useState } from 'react';
import { Button, Input, definePlugin } from '@runkun/api';

function MyPlugin() {
  const [name, setName] = useState('');
  const [count, setCount] = useState(0);

  return (
    <div className="p-6 space-y-4">
      <h2 className="text-2xl font-bold">My Plugin</h2>
      
      <Input
        label="Your Name"
        placeholder="Enter your name"
        value={name}
        onChange={setName}
      />
      
      <Button
        title={`Clicked ${count} times`}
        onClick={() => setCount(c => c + 1)}
      />
      
      {name && <p>Hello, {name}!</p>}
    </div>
  );
}

export default definePlugin({
  metadata: {
    id: 'my-plugin',
    name: 'My Plugin',
    version: '1.0.0',
    description: 'A simple example plugin',
    author: 'Your Name',
  },
  component: MyPlugin,
});

For Host Application Developers

// 1. Install dependencies
pnpm add @runkun/core @runkun/adapter-svelte

// 2. Set up the adapter in your Svelte app
<script>
  import { SvelteAdapter } from '@runkun/adapter-svelte';
  import { ComponentRenderer } from '@runkun/adapter-svelte';
  import { Button, Input } from './components/ui'; // Your UI components
  import MyPlugin from 'my-plugin';

  const adapter = new SvelteAdapter();
  
  // Register your UI components
  adapter.registerComponent('Button', Button);
  adapter.registerComponent('Input', Input);
</script>

<ComponentRenderer 
  instance={pluginTree} 
  {adapter} 
/>

📦 Packages

This is a monorepo containing the following packages:

Package	Description	Version	Status
@runkun/core	Core runtime with custom React reconciler	0.1.0	✅ Ready
@runkun/api	React API for plugin development	0.1.0	✅ Ready
@runkun/adapter-svelte	Svelte framework adapter	0.1.0	✅ Ready
@runkun/runtime	Runtime orchestrator	0.1.0	🚧 In Progress
@runkun/adapter-vue	Vue framework adapter	-	🎯 Planned
@runkun/adapter-react	React framework adapter	-	🎯 Planned
@runkun/cli	CLI tools	-	🎯 Planned

🎨 Runtime Modes

Runkun supports three runtime modes for different use cases:

1. Web Worker Mode (Sandboxed) ⚡

• Security: Complete isolation from main thread
• Use Case: Production, untrusted plugins, plugin marketplaces
• Performance: ~5-10ms event latency
• Loading: Can load from any URL

2. Main Thread Mode (Direct) 🧵

• Security: No isolation, shares execution context
• Use Case: Development, trusted plugins, performance-critical
• Performance: <1ms event latency
• Loading: Direct imports

3. Node.js WebSocket Mode (Server Runtime) 🖥️

• Security: Server-side isolation
• Use Case: Raycast-like apps, desktop applications
• Performance: ~5-10ms event latency
• Features: Full Node.js API access, hot reload

🧪 Examples

• Svelte Host App - SvelteKit application with plugin system
• Plugin Examples - Example plugins (Coming Soon)
• Vue Host App - Vue 3 host example (Coming Soon)

🛠️ Development

# Install dependencies
pnpm install

# Build all packages
pnpm build

# Start development mode
pnpm dev

# Run tests
pnpm test

# Type checking
pnpm typecheck

📚 Documentation

• Architecture Design - Detailed technical design
• Implementation Plan - Development roadmap
• Executive Summary - Project overview

🗺️ Roadmap

Phase 1: Foundation ✅ (Completed)

• Core reconciler and bridge
• Component serialization system
• Svelte adapter implementation
• Basic plugin API

Phase 2: Multi-Framework Support 🚧 (In Progress)

• Vue adapter
• React adapter
• Framework adapter base classes
• Cross-framework testing

Phase 3: Runtime Optimization 🎯 (Planned)

• Worker runtime optimization
• Node.js WebSocket mode
• Performance benchmarking
• Security enhancements

Phase 4: Developer Experience 🎯 (Planned)

• CLI tools for scaffolding
• DevTools and debugging
• Comprehensive documentation
• Example applications

🤝 Contributing

Contributions are welcome! Please see CONTRIBUTING.md for details.

📄 License

MIT © Runkun Team

🙏 Acknowledgments

Inspired by successful React reconciler projects:

• Raycast - React → macOS AppKit
• React Native - React → iOS/Android
• Remotion - React → Video

Built on top of:

• React Reconciler
• kkRPC - Bidirectional RPC communication
• Svelte 5 - For the reference implementation

---

Ready to build the next generation plugin system? 🚀