create-lego-one 2.0.12 → 2.0.14

package/template/docs/framework/setup/07-plugin-development.md

@@ -0,0 +1,582 @@
+# Plugin Development
+
+**Complete Guide to Creating Lego-One Plugins**
+
+---
+
+## Overview
+
+Lego-One plugins are Modern.js micro-frontends that integrate seamlessly with the host application. This guide provides complete instructions for creating plugins.
+
+---
+
+## Plugin Structure
+
+### Standard Plugin File Structure
+
+```
+packages/plugins/@lego/plugin-<name>/
+├── package.json           # Package configuration
+├── tsconfig.json          # TypeScript configuration
+├── modern.config.ts       # Modern.js configuration
+├── tailwind.config.ts     # Tailwind CSS configuration
+├── postcss.config.mjs     # PostCSS configuration
+└── src/
+    ├── global.css         # Global styles
+    ├── plugin.config.ts   # Plugin manifest and configuration
+    ├── plugin.ts          # Plugin exports for Garfish
+    ├── App.tsx            # Root component with routing
+    ├── types.ts           # TypeScript types
+    ├── schemas.ts         # Zod validation schemas
+    ├── pages/             # Route pages
+    │   └── <Plugin>Page.tsx
+    ├── components/        # React components
+    │   └── slots/         # Slot injection components
+    │       └── SidebarWidget.tsx
+    ├── hooks/             # Custom React hooks
+    │   ├── usePocketBase.ts
+    │   └── use<Feature>Data.ts
+    └── vite-env.d.ts      # Vite type declarations
+```
+
+---
+
+## Step-by-Step Plugin Creation
+
+### Step 1: Create Plugin Directory
+
+```bash
+mkdir -p packages/plugins/@lego/plugin-my-plugin
+cd packages/plugins/@lego/plugin-my-plugin
+```
+
+### Step 2: Create package.json
+
+```json
+{
+  "name": "@lego/plugin-my-plugin",
+  "version": "1.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "modern dev",
+    "build": "modern build",
+    "start": "modern start"
+  },
+  "dependencies": {
+    "@garfish/hooks": "^1.22.0",
+    "@modern-js/runtime": "^2.60.0",
+    "@modern-js/runtime/garfish": "^2.60.0",
+    "@tanstack/react-query": "^5.59.0",
+    "lucide-react": "^0.454.0",
+    "pocketbase": "^0.21.5",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@modern-js/app-tools": "^2.60.0",
+    "@modern-js/plugin-garfish": "^2.60.0",
+    "tailwindcss": "^3.4.0",
+    "typescript": "^5.3.0"
+  }
+}
+```
+
+### Step 3: Create modern.config.ts
+
+```typescript
+import { appTools, defineConfig } from '@modern-js/app-tools';
+import { garfishPlugin } from '@modern-js/plugin-garfish';
+
+export default defineConfig({
+  dev: {
+    port: 3003, // Unique port for each plugin
+  },
+  runtime: {
+    router: true,
+    state: true,
+  },
+  deploy: {
+    microFrontend: true,
+  },
+  plugins: [appTools(), garfishPlugin()],
+});
+```
+
+### Step 4: Create types.ts
+
+```typescript
+export interface MyEntity {
+  id: string;
+  name: string;
+  description?: string;
+  organizationId: string;
+  ownerId: string;
+  created: string;
+  updated: string;
+}
+
+export interface MyEntityFormData {
+  name: string;
+  description?: string;
+}
+```
+
+### Step 5: Create schemas.ts
+
+```typescript
+import { z } from 'zod';
+
+export const myEntityFormSchema = z.object({
+  name: z.string().min(1, 'Name is required').max(200, 'Name too long'),
+  description: z.string().max(1000).optional(),
+});
+```
+
+### Step 6: Create hooks/usePocketBase.ts
+
+```typescript
+import { useEffect, useState } from 'react';
+
+export function usePocketBase() {
+  const [pb, setPb] = useState(null);
+
+  useEffect(() => {
+    const kernelState = window.__LEGO_KERNEL_STATE__;
+    const pbUrl = import.meta.env.VITE_POCKETBASE_URL || 'http://127.0.0.1:8090';
+    const PocketBase = require('pocketbase').default;
+    const client = new PocketBase(pbUrl);
+
+    const state = kernelState?.useGlobalKernelState?.getState();
+    if (state?.token) {
+      client.authStore.save(state.token);
+    }
+
+    setPb(client);
+  }, []);
+
+  return pb;
+}
+```
+
+### Step 7: Create hooks/useMyEntities.ts
+
+```typescript
+import { useQuery } from '@tanstack/react-query';
+import { usePocketBase } from './usePocketBase';
+
+export function useMyEntities() {
+  const pb = usePocketBase();
+
+  return useQuery({
+    queryKey: ['my-entities'],
+    queryFn: async () => {
+      if (!pb) throw new Error('PB not initialized');
+
+      const kernelState = window.__LEGO_KERNEL_STATE__;
+      const state = kernelState?.useGlobalKernelState?.getState();
+      const orgId = state?.organization?.id;
+
+      const result = await pb.collection('my_entities').getList(1, 50, {
+        filter: `organizationId = "${orgId}"`,
+        sort: '-created',
+      });
+
+      return result.items;
+    },
+    enabled: !!pb,
+  });
+}
+```
+
+### Step 8: Create plugin.config.ts
+
+```typescript
+import type { PluginConfig } from '@lego/kernel/plugins';
+import { SidebarWidget } from './components/slots/SidebarWidget';
+
+export const pluginConfig: PluginConfig = {
+  manifest: {
+    name: '@lego/plugin-my-plugin',
+    version: '1.0.0',
+    displayName: 'My Plugin',
+    description: 'Description of what this plugin does',
+    permissions: ['myplugin.read', 'myplugin.write'],
+  },
+  enabled: true,
+  slots: [
+    {
+      slot: 'sidebar:nav',
+      component: () => import('./components/slots/SidebarWidget').then(m => m.default),
+      order: 100,
+    },
+  ],
+  routes: [
+    {
+      path: '/my-plugin',
+      component: () => import('./pages/MyPluginPage').then(m => m.default),
+      protected: true,
+      permissions: ['myplugin.read'],
+    },
+  ],
+};
+```
+
+### Step 9: Create plugin.ts
+
+```typescript
+import { pluginConfig } from './plugin.config';
+import App from './App';
+
+export default {
+  config: pluginConfig,
+  App,
+};
+```
+
+### Step 10: Create App.tsx
+
+```typescript
+import { Route, Routes } from '@modern-js/runtime/router';
+import { MyPluginPage } from './pages/MyPluginPage';
+
+export function App() {
+  return (
+    <Routes>
+      <Route path="/my-plugin" element={<MyPluginPage />} />
+    </Routes>
+  );
+}
+
+export default App;
+```
+
+### Step 11: Create components/slots/SidebarWidget.tsx
+
+```typescript
+import { NavLink } from '@modern-js/runtime/router';
+import { MyIcon } from 'lucide-react';
+
+export function SidebarWidget() {
+  return (
+    <NavLink
+      to="/my-plugin"
+      className={({ isActive }) =>
+        `flex items-center gap-3 rounded-lg px-3 py-2 text-sm font-medium transition-colors ${
+          isActive
+            ? 'bg-primary text-primary-foreground'
+            : 'text-muted-foreground hover:bg-muted hover:text-foreground'
+        }`
+      }
+    >
+      <MyIcon className="h-5 w-5" />
+      <span>My Plugin</span>
+    </NavLink>
+  );
+}
+
+export default SidebarWidget;
+```
+
+### Step 12: Create pages/MyPluginPage.tsx
+
+```typescript
+import { useMyEntities } from '../hooks/useMyEntities';
+
+export function MyPluginPage() {
+  const { data: entities, isLoading } = useMyEntities();
+
+  if (isLoading) {
+    return <div className="p-8">Loading...</div>;
+  }
+
+  return (
+    <div className="container mx-auto p-8">
+      <h1 className="text-3xl font-bold">My Plugin</h1>
+      <div className="mt-6 space-y-4">
+        {entities?.map((entity) => (
+          <div key={entity.id} className="rounded border p-4">
+            <h3 className="font-semibold">{entity.name}</h3>
+            <p className="text-muted-foreground">{entity.description}</p>
+          </div>
+        ))}
+      </div>
+    </div>
+  );
+}
+
+export default MyPluginPage;
+```
+
+### Step 13: Create global.css
+
+```css
+@tailwind base;
+@tailwind components;
+@tailwind utilities;
+
+@layer base {
+  :root {
+    --background: 0 0% 100%;
+    --foreground: 222.2 84% 4.9%;
+    /* ... more variables */
+  }
+}
+```
+
+### Step 14: Create tailwind.config.ts
+
+```typescript
+import type { Config } from 'tailwindcss';
+
+export default {
+  darkMode: ['class'],
+  content: ['./src/**/*.{ts,tsx}'],
+  theme: {
+    extend: {
+      colors: {
+        border: 'hsl(var(--border))',
+        input: 'hsl(var(--input))',
+        ring: 'hsl(var(--ring))',
+        background: 'hsl(var(--background))',
+        foreground: 'hsl(var(--foreground))',
+        primary: {
+          DEFAULT: 'hsl(var(--primary))',
+          foreground: 'hsl(var(--primary-foreground))',
+        },
+        /* ... more colors */
+      },
+    },
+  },
+  plugins: [],
+} satisfies Config;
+```
+
+### Step 15: Create postcss.config.mjs
+
+```javascript
+export default {
+  plugins: {
+    tailwindcss: {},
+    autoprefixer: {},
+  },
+};
+```
+
+### Step 16: Create tsconfig.json
+
+```json
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "jsx": "react-jsx",
+    "moduleResolution": "bundler",
+    "resolveJsonModule": true,
+    "allowJs": true,
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "isolatedModules": true,
+    "noEmit": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}
+```
+
+### Step 17: Create vite-env.d.ts
+
+```typescript
+declare global {
+  interface Window {
+    __LEGO_KERNEL_STATE__?: {
+      user?: { id: string; email: string; name?: string } | null;
+      organization?: { id: string; name: string; slug: string } | null;
+      isAuthenticated: boolean;
+      useGlobalKernelState?: any;
+    };
+    __LEGO_CHANNEL_BUS__?: {
+      publish: (channel: string, message: any) => void;
+      subscribe: (channel: string, callback: (data: any) => void) => () => void;
+    };
+  }
+}
+
+export {};
+```
+
+---
+
+## Register Plugin with Host
+
+### Step 1: Update host/src/modern.runtime.ts
+
+```typescript
+export default defineRuntimeConfig({
+  masterApp: {
+    apps: [
+      // ... existing apps
+      {
+        name: '@lego/plugin-my-plugin',
+        entry: isDev
+          ? 'http://localhost:3003'
+          : () => import('@lego/plugin-my-plugin'),
+        activeWhen: '/my-plugin',
+      },
+    ],
+  },
+});
+```
+
+### Step 2: Update host/src/saas.config.ts
+
+```typescript
+export const saasConfig = {
+  plugins: [
+    // ... existing plugins
+    { name: '@lego/plugin-my-plugin', enabled: true },
+  ],
+};
+```
+
+---
+
+## Plugin Patterns
+
+### CRUD Pattern (Like Todo Plugin)
+
+1. **Types** → Define data interfaces
+2. **Schemas** → Zod validation
+3. **Hooks** → usePocketBase, useItems, useCreate, useUpdate, useDelete
+4. **Components** → List, Item, Form, Dialog
+5. **Pages** → Main page with filters
+
+### Display Pattern (Like Dashboard Plugin)
+
+1. **Hooks** → Stats queries, activity feed
+2. **Components** → Stat cards, activity feed, quick actions
+3. **Pages** → Dashboard overview
+
+### Calculation Pattern
+
+1. **Types** → Input/Output types
+2. **Hooks** → Pure calculation functions
+3. **Components** → Input form, result display
+4. **Pages** → Calculator page
+
+---
+
+## Multi-Tenancy for Plugins
+
+### Data Isolation
+
+All plugin data MUST be scoped to organization:
+
+```typescript
+const result = await pb.collection('my_entities').getList(1, 50, {
+  filter: `organizationId = "${orgId}"`,
+});
+```
+
+### PocketBase Collection Pattern
+
+```javascript
+{
+  name: 'my_entities',
+  type: 'base',
+  fields: [
+    // Multi-tenancy required fields
+    { name: 'organizationId', type: 'relation', required: true, options: {
+      collectionId: 'organizations',
+      displayFields: ['name']
+    }},
+    { name: 'ownerId', type: 'relation', required: true, options: {
+      collectionId: 'users',
+      displayFields: ['name', 'email']
+    }},
+    // Your fields here
+    { name: 'name', type: 'text', required: true },
+    { name: 'description', type: 'text' },
+  ],
+  // Multi-tenancy API rules
+  listRule: '@request.auth.id != "" && organizationId = @request.auth.membership.organizations',
+  viewRule: '@request.auth.id != "" && organizationId = @request.auth.membership.organizations',
+  createRule: '@request.auth.id != "" && organizationId = @request.auth.membership.organizations',
+  updateRule: '@request.auth.id != "" && organizationId = @request.auth.membership.organizations && ownerId = @request.auth.id',
+  deleteRule: '@request.auth.id != "" && organizationId = @request.auth.membership.organizations && ownerId = @request.auth.id',
+}
+```
+
+---
+
+## Testing Your Plugin
+
+### Local Development
+
+1. **Start plugin dev server:**
+```bash
+cd packages/plugins/@lego/plugin-my-plugin
+pnpm run dev
+```
+
+2. **Start host:**
+```bash
+cd host
+pnpm run dev
+```
+
+3. **Navigate to:** http://localhost:8080
+
+4. **Plugin should appear** in sidebar navigation
+
+### Production Build Test
+
+```bash
+# Build all
+pnpm run build
+
+# Start production server
+cd host && pnpm run start
+
+# Navigate to http://localhost:8080
+# Plugin should still work
+```
+
+---
+
+## Common Issues
+
+### Plugin Not Loading
+
+**Checklist:**
+- [ ] Plugin enabled in `saas.config.ts`
+- [ ] Plugin registered in `modern.runtime.ts`
+- [ ] Plugin dev server running (dev mode)
+- [ ] Correct `activeWhen` path
+- [ ] No console errors
+
+### Window Bridge Undefined
+
+**Solution:** Add type definitions in `vite-env.d.ts`
+
+### Styles Not Loading
+
+**Solutions:**
+- [ ] `global.css` imported in `App.tsx`
+- [ ] Tailwind content paths correct
+- [ ] PostCSS config present
+
+### Route Not Working
+
+**Solutions:**
+- [ ] Route defined in `plugin.config.ts`
+- [ ] Component export matches
+- [ ] Path doesn't conflict with existing routes
+
+---
+
+**Next:** Read [`08-component-library.md`](./08-component-library.md) for UI components reference.