create-lego-one 2.0.12 → 2.0.14

package/template/docs/framework/research/04-plugin-architecture.md

@@ -0,0 +1,645 @@
+# Plugin Architecture: Hello World & Registration
+
+**Project:** Lego-One (Modern.js SaaS OS)
+**Document:** 04 - Plugin Architecture
+**Status:** Research Phase
+
+## Executive Summary
+
+This document explains how to create a "Hello World" plugin as a standalone Modern.js sub-app and register it with the Host (Kernel). Plugins are independently deployable Modern.js applications that can run standalone or be loaded by the host.
+
+---
+
+## 1. Plugin Structure Overview
+
+### 1.1 Directory Structure
+
+```
+lego-one/
+├── host/                          # Kernel application
+├── packages/
+│   └── plugins/
+│       └── @lego/
+│           └── plugin-hello/      # Hello World plugin
+│               ├── modern.config.ts
+│               ├── package.json
+│               ├── plugin.config.ts
+│               ├── tsconfig.json
+│               └── src/
+│                   ├── App.tsx
+│                   ├── main.tsx
+│                   ├── pages/
+│                   │   └── HelloPage.tsx
+│                   ├── components/
+│                   │   └── Greeting.tsx
+│                   ├── hooks/
+│                   │   ├── useKernelState.ts
+│                   │   └── useKernelBus.ts
+│                   └── lib/
+│                       └── utils.ts
+```
+
+### 1.2 Plugin Types
+
+| Type | Description | Example |
+|------|-------------|---------|
+| **Feature Plugin** | Standalone business functionality | Loan Calculator, Inventory |
+| **Integration Plugin** | Third-party service integration | Stripe, Snowflake, SendGrid |
+| **UI Extension** | Extends host UI (slots) | Dashboard widget, Sidebar link |
+
+---
+
+## 2. Create Hello World Plugin
+
+### 2.1 Initialize Plugin Project
+
+```bash
+cd lego-one/packages/plugins/@lego
+
+# Create plugin using Modern.js
+npx @modern-js/create@latest plugin-hello
+
+cd plugin-hello
+
+# Enable Micro Frontend
+pnpm run new
+# Select: Enable features -> Micro Front-end Feature
+```
+
+### 2.2 Configure Package.json
+
+**File:** `packages/plugins/@lego/plugin-hello/package.json`
+
+```json
+{
+  "name": "@lego/plugin-hello",
+  "version": "1.0.0",
+  "private": true,
+  "type": "module",
+  "exports": {
+    ".": "./src/main.tsx",
+    "./plugin.config": "./plugin.config.ts"
+  },
+  "scripts": {
+    "dev": "modern dev",
+    "build": "modern build",
+    "preview": "modern preview",
+    "lint": "modern lint"
+  },
+  "dependencies": {
+    "@modern-js/runtime": "^2.0.0",
+    "react": "^18.3.0",
+    "react-dom": "^18.3.0"
+  },
+  "devDependencies": {
+    "@modern-js/app-tools": "^2.0.0",
+    "@modern-js/plugin-garfish": "^2.0.0",
+    "@types/react": "^18.3.0",
+    "@types/react-dom": "^18.3.0",
+    "typescript": "^5.5.0"
+  }
+}
+```
+
+### 2.3 Configure Modern.js
+
+**File:** `packages/plugins/@lego/plugin-hello/modern.config.ts`
+
+```typescript
+import { appTools, defineConfig } from '@modern-js/app-tools';
+import { garfishPlugin } from '@modern-js/plugin-garfish';
+
+export default defineConfig({
+  // Unique dev port for each plugin
+  dev: {
+    port: 3001,
+  },
+
+  // Enable routing
+  runtime: {
+    router: true,
+  },
+
+  // CRITICAL: Mark as micro-frontend sub-app
+  deploy: {
+    microFrontend: true,
+  },
+
+  plugins: [appTools(), garfishPlugin()],
+
+  // Path aliases
+  source: {
+    alias: {
+      '@': './src',
+    },
+  },
+});
+```
+
+### 2.4 Create Plugin Config
+
+**File:** `packages/plugins/@lego/plugin-hello/plugin.config.ts`
+
+```typescript
+import { definePluginConfig } from '@lego/kernel/plugin-config';
+
+export default definePluginConfig({
+  name: '@lego/plugin-hello',
+  version: '1.0.0',
+  displayName: 'Hello World',
+  description: 'A simple Hello World plugin for demonstration',
+
+  // Plugin exports available to host
+  exports: {
+    components: {
+      Greeting: './src/components/Greeting',
+    },
+    hooks: {
+      useHello: './src/hooks/useHello',
+    },
+  },
+
+  // Slot injections
+  slots: {
+    'sidebar:nav': {
+      component: './src/components/SidebarLink',
+      order: 100,
+    },
+  },
+
+  // Routes this plugin handles
+  routes: {
+    basePath: '/hello',
+    children: ['/', '/greeting'],
+  },
+});
+```
+
+### 2.5 Create Plugin Entry Point
+
+**File:** `packages/plugins/@lego/plugin-hello/src/App.tsx`
+
+```typescript
+import { BrowserRouter, Routes, Route } from '@modern-js/runtime/router';
+import { useGarfish } from '@garfish/hooks';
+import { useEffect, useState } from 'react';
+import { HelloPage } from './pages/HelloPage';
+import { GreetingPage } from './pages/GreetingPage';
+import pluginConfig from '../../plugin.config';
+import { registerSlots } from './lib/slot-registration';
+
+interface PluginProps {
+  basename?: string;
+}
+
+export default function PluginApp(props: PluginProps) {
+  const { appInfo } = useGarfish();
+  const basename = props.basename || '/hello';
+
+  useEffect(() => {
+    console.log(`[${pluginConfig.name}] Plugin loaded with appInfo:`, appInfo);
+
+    // Register slot injections with host
+    registerSlots(pluginConfig.slots);
+  }, [appInfo]);
+
+  return (
+    <BrowserRouter basename={basename}>
+      <Routes>
+        <Route index element={<HelloPage />} />
+        <Route path="greeting" element={<GreetingPage />} />
+      </Routes>
+    </BrowserRouter>
+  );
+}
+```
+
+### 2.6 Create Pages
+
+**File:** `packages/plugins/@lego/plugin-hello/src/pages/HelloPage.tsx`
+
+```typescript
+import { useKernelState } from '../hooks/useKernelState';
+import { useKernelBus } from '../hooks/useKernelBus';
+import { Button } from '../components/ui/button';
+
+export function HelloPage() {
+  const kernelState = useKernelState();
+  const bus = useKernelBus();
+
+  const handleGreet = () => {
+    // Emit event to host for toast notification
+    bus.emit({
+      type: 'toast:show',
+      payload: { message: 'Hello from the plugin!', variant: 'success' },
+    });
+  };
+
+  return (
+    <div className="p-8">
+      <h1 className="text-3xl font-bold mb-4">Hello World Plugin</h1>
+
+      <div className="space-y-4">
+        <p className="text-muted-foreground">
+          This is a standalone Modern.js application running as a micro-frontend.
+        </p>
+
+        <div className="bg-muted p-4 rounded-lg">
+          <h2 className="font-semibold mb-2">Shared State from Kernel:</h2>
+          <ul className="list-disc list-inside space-y-1">
+            <li>Theme: {kernelState?.theme}</li>
+            <li>Sidebar: {kernelState?.sidebarOpen ? 'Open' : 'Closed'}</li>
+            <li>User: {kernelState?.currentUser?.email || 'Not authenticated'}</li>
+          </ul>
+        </div>
+
+        <Button onClick={handleGreet}>Show Greeting</Button>
+      </div>
+    </div>
+  );
+}
+```
+
+**File:** `packages/plugins/@lego/plugin-hello/src/pages/GreetingPage.tsx`
+
+```typescript
+import { Greeting } from '../components/Greeting';
+
+export function GreetingPage() {
+  return (
+    <div className="p-8">
+      <h1 className="text-3xl font-bold mb-4">Greeting Page</h1>
+      <Greeting name="Developer" />
+    </div>
+  );
+}
+```
+
+### 2.7 Create Components
+
+**File:** `packages/plugins/@lego/plugin-hello/src/components/Greeting.tsx`
+
+```typescript
+import { useState } from 'react';
+
+interface GreetingProps {
+  name: string;
+}
+
+export function Greeting({ name }: GreetingProps) {
+  const [count, setCount] = useState(0);
+
+  return (
+    <div className="bg-card p-6 rounded-lg border">
+      <p className="text-lg">
+        Hello, <span className="font-semibold text-primary">{name}</span>!
+      </p>
+      <p className="text-muted-foreground mt-2">
+        You've clicked the button {count} times.
+      </p>
+      <button
+        onClick={() => setCount((c) => c + 1)}
+        className="mt-4 px-4 py-2 bg-primary text-primary-foreground rounded-md"
+      >
+        Click Me
+      </button>
+    </div>
+  );
+}
+```
+
+**File:** `packages/plugins/@lego/plugin-hello/src/components/SidebarLink.tsx`
+
+```typescript
+import { Link } from '@modern-js/runtime/router';
+import { Hand } from 'lucide-react';
+
+export function SidebarLink() {
+  return (
+    <Link
+      to="/hello"
+      className="flex items-center gap-2 px-3 py-2 text-sm rounded-md hover:bg-accent hover:text-accent-foreground"
+    >
+      <Hand className="h-4 w-4" />
+      <span>Hello Plugin</span>
+    </Link>
+  );
+}
+```
+
+### 2.8 Create Hooks
+
+**File:** `packages/plugins/@lego/plugin-hello/src/hooks/useKernelState.ts`
+
+```typescript
+import { useEffect, useState } from 'react';
+
+interface KernelState {
+  currentUser: { id: string; email: string; role: string } | null;
+  theme: 'light' | 'dark';
+  sidebarOpen: boolean;
+}
+
+export function useKernelState() {
+  const [state, setState] = useState<KernelState | null>(null);
+
+  useEffect(() => {
+    // Access shared state bridge from host
+    const kernelBridge = (window as any).__LEGO_KERNEL_STATE__;
+
+    if (kernelBridge?.useGlobalKernelState) {
+      // Subscribe to state changes
+      const unsubscribe = kernelBridge.useGlobalKernelState.subscribe(
+        (newState: KernelState) => {
+          setState({ ...newState });
+        }
+      );
+
+      // Initialize with current state
+      setState(kernelBridge.useGlobalKernelState.getState());
+
+      return () => unsubscribe?.();
+    }
+  }, []);
+
+  return state;
+}
+```
+
+**File:** `packages/plugins/@lego/plugin-hello/src/hooks/useKernelBus.ts`
+
+```typescript
+import { Garfish } from 'garfish';
+
+type BusEvent =
+  | { type: 'toast:show'; payload: { message: string; variant: 'success' | 'error' } }
+  | { type: 'navigation:goto'; payload: { path: string } };
+
+export function useKernelBus() {
+  const channel = Garfish.channel;
+
+  return {
+    emit: (event: BusEvent) => {
+      channel.emit(event.type, event.payload);
+    },
+    on: (eventType: BusEvent['type'], handler: (payload: any) => void) => {
+      channel.on(eventType, handler);
+    },
+    off: (eventType: BusEvent['type'], handler: (payload: any) => void) => {
+      channel.off(eventType, handler);
+    },
+  };
+}
+```
+
+### 2.9 Create Slot Registration Helper
+
+**File:** `packages/plugins/@lego/plugin-hello/src/lib/slot-registration.ts`
+
+```typescript
+interface SlotConfig {
+  component: string;
+  order: number;
+  isVisible?: () => boolean;
+}
+
+interface SlotsConfig {
+  [slotName: string]: SlotConfig;
+}
+
+export async function registerSlots(slots: SlotsConfig) {
+  const slotRegistry = (window as any).__LEGO_SLOT_REGISTRY__;
+
+  if (!slotRegistry) {
+    console.warn('Slot registry not found. Host may not be initialized.');
+    return;
+  }
+
+  for (const [slotName, slotConfig] of Object.entries(slots)) {
+    try {
+      const module = await import(/* @vite-ignore */ slotConfig.component);
+      const Component = module.default;
+
+      slotRegistry.register(slotName, {
+        id: `${slotName}-${Date.now()}`,
+        pluginName: '@lego/plugin-hello',
+        component: Component,
+        order: slotConfig.order,
+        isVisible: slotConfig.isVisible || (() => true),
+      });
+
+      console.log(`[Slot] Registered "${slotName}" for @lego/plugin-hello`);
+    } catch (error) {
+      console.error(`[Slot] Failed to register "${slotName}":`, error);
+    }
+  }
+}
+```
+
+---
+
+## 3. Register Plugin with Host
+
+### 3.1 Update Host Configuration
+
+**File:** `host/src/modern.runtime.ts`
+
+```typescript
+import { defineRuntimeConfig } from '@modern-js/runtime';
+
+export default defineRuntimeConfig({
+  masterApp: {
+    apps: [
+      {
+        name: '@lego/plugin-hello',
+        entry: 'http://localhost:3001',
+        activeWhen: '/hello',
+      },
+    ],
+  },
+});
+```
+
+### 3.2 Create Plugin Route in Host
+
+**File:** `host/src/routes/hello/$.tsx`
+
+```typescript
+import { useModuleApps } from '@modern-js/plugin-garfish/runtime';
+
+export default function HelloRoute() {
+  const { Hello } = useModuleApps();
+
+  return <Hello />;
+}
+```
+
+### 3.3 Update Host saas.config.ts
+
+**File:** `host/saas.config.ts`
+
+```typescript
+import { defineConfig } from '@lego/kernel/config';
+
+export default defineConfig({
+  plugins: [
+    {
+      name: '@lego/plugin-hello',
+      enabled: true,
+    },
+  ],
+});
+```
+
+---
+
+## 4. Development Workflow
+
+### 4.1 Start Host and Plugin
+
+Open two terminal windows:
+
+```bash
+# Terminal 1: Start Host
+cd host
+pnpm run dev
+# Runs on http://localhost:8080
+```
+
+```bash
+# Terminal 2: Start Plugin
+cd packages/plugins/@lego/plugin-hello
+pnpm run dev
+# Runs on http://localhost:3001
+```
+
+### 4.2 Test Plugin
+
+Navigate to `http://localhost:8080/hello`
+
+**Expected behavior:**
+1. Host loads the Hello plugin at the `/hello` route
+2. Plugin displays "Hello World Plugin" header
+3. Shared kernel state (theme, user, sidebar) is displayed
+4. "Show Greeting" button triggers toast in host app
+5. Sidebar shows "Hello Plugin" link (if slot injection works)
+
+---
+
+## 5. Plugin Lifecycle
+
+```
+┌─────────────────────────────────────────────────────────────────────────┐
+│                          Plugin Lifecycle                               │
+├─────────────────────────────────────────────────────────────────────────┤
+│                                                                           │
+│  1. REGISTRATION                                                         │
+│     - Plugin listed in saas.config.ts                                    │
+│     - Host reads plugin config on startup                                │
+│                                                                           │
+│  2. LOADING                                                              │
+│     - User navigates to plugin route (/hello)                            │
+│     - Garfish.loadApp() fetches plugin entry                             │
+│     - Plugin JavaScript executes                                         │
+│                                                                           │
+│  3. MOUNTING                                                             │
+│     - Plugin App.tsx receives basename prop                              │
+│     - Plugin registers slots with host                                  │
+│     - Plugin subscribes to kernel bus events                             │
+│     - Plugin ReactDOM.render into container                              │
+│                                                                           │
+│  4. ACTIVE STATE                                                         │
+│     - Plugin handles its own routing                                     │
+│     - Plugin communicates with host via bus                              │
+│     - Plugin accesses shared state via window bridge                     │
+│                                                                           │
+│  5. UNMOUNTING                                                           │
+│     - User navigates away from plugin route                              │
+│     - Plugin cleanup functions run                                       │
+│     - Garfish unloads plugin resources                                   │
+│                                                                           │
+└─────────────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 6. Standalone Development
+
+Plugins can run independently for development:
+
+```bash
+cd packages/plugins/@lego/plugin-hello
+pnpm run dev
+# Access at http://localhost:3001
+```
+
+**Standalone App.tsx:**
+
+```typescript
+// For standalone development, provide a default basename
+export default function PluginApp(props: PluginProps) {
+  const basename = props.basename || '/hello';
+  // ... rest of component
+}
+```
+
+---
+
+## 7. Plugin Best Practices
+
+| Practice | Description |
+|----------|-------------|
+| **Unique Ports** | Each plugin needs a unique dev port |
+| **Isolated State** | Don't rely on host state for core functionality |
+| **Error Boundaries** | Wrap plugin in error boundary |
+| **Type Safety** | Export types from plugin.config.ts |
+| **Testing** | Test plugin standalone and integrated |
+| **Documentation** | Document slots, events, and exports |
+
+---
+
+## 8. Troubleshooting
+
+### 8.1 Plugin Not Loading
+
+**Symptoms:** Blank page at plugin route
+
+**Solutions:**
+1. Check plugin dev server is running
+2. Verify `activeWhen` matches route
+3. Check browser console for errors
+4. Verify `deploy.microFrontend: true` in plugin config
+
+### 8.2 Shared State Undefined
+
+**Symptoms:** `useKernelState()` returns null
+
+**Solutions:**
+1. Verify host has called `registerSharedState()`
+2. Check `window.__LEGO_KERNEL_STATE__` exists
+3. Ensure host loads before plugin
+
+### 8.3 Route Mismatch
+
+**Symptoms:** 404 when navigating to plugin
+
+**Solutions:**
+1. Check `$.tsx` file exists in host routes
+2. Verify `basename` prop is passed correctly
+3. Check for conflicts with other routes
+
+---
+
+## 9. Next Steps
+
+1. **`05-slot-injection-pattern.md`**: Advanced slot injection patterns
+2. **`06-cli-strategy.md`**: Automate plugin creation with CLI
+3. **`07-deployment.md`**: Deploy plugins to production
+
+---
+
+## References
+
+- [Modern.js Micro Frontend Development](https://modernjs.dev/guides/topic-detail/micro-frontend/c02-development)
+- [Garfish Documentation](https://www.garfishjs.org/)
+- [Garfish.setExternal API](https://www.garfishjs.org/api/setExternal.html)