Add documentation for lazy-loaded plugins architecture

Copilot · hotlong · Copilot · commit c808ca281733 · 2026-01-14T13:35:22.000Z
Co-authored-by: hotlong &lt;50353452+hotlong@users.noreply.github.com&gt;
diff --git a/docs/lazy-loaded-plugins.md b/docs/lazy-loaded-plugins.md
@@ -0,0 +1,231 @@
+# Lazy-Loaded Plugins Architecture
+
+This document explains how Object UI implements lazy-loaded plugins to optimize bundle size.
+
+## Overview
+
+Object UI supports heavy components (like Monaco Editor and Recharts) as separate plugin packages that are lazy-loaded on demand. This keeps the main application bundle small while still providing powerful functionality.
+
+## Architecture
+
+### Traditional Approach (Bad ❌)
+```typescript
+// This loads Monaco Editor immediately, even if never used
+import Editor from '@monaco-editor/react';
+
+function CodeEditor() {
+  return <Editor {...props} />;
+}
+```
+
+### Lazy Loading - Host App Responsibility (Not Ideal ⚠️)
+```typescript
+// Forces every app to implement lazy loading
+const CodeEditor = React.lazy(() => import('./CodeEditor'));
+
+function App() {
+  return (
+    <Suspense fallback={<Skeleton />}>
+      <CodeEditor />
+    </Suspense>
+  );
+}
+```
+
+### Internal Lazy Loading (Best ✅)
+```typescript
+// The plugin handles lazy loading internally
+import '@object-ui/plugin-editor';
+
+// Monaco is NOT loaded yet
+// It only loads when a code-editor component is rendered
+const schema = { type: 'code-editor', value: '...' };
+```
+
+## Implementation Pattern
+
+Each plugin package follows this structure:
+
+### 1. Heavy Implementation File (`XxxImpl.tsx`)
+```typescript
+// packages/plugin-editor/src/MonacoImpl.tsx
+import Editor from '@monaco-editor/react'; // Heavy import
+
+export default function MonacoImpl(props) {
+  return <Editor {...props} />;
+}
+```
+
+### 2. Lazy Wrapper (`index.tsx`)
+```typescript
+// packages/plugin-editor/src/index.tsx
+import React, { Suspense } from 'react';
+import { Skeleton } from '@object-ui/components';
+
+// Lazy load the implementation
+const LazyMonacoEditor = React.lazy(() => import('./MonacoImpl'));
+
+export const CodeEditorRenderer = (props) => (
+  <Suspense fallback={<Skeleton className="w-full h-[400px]" />}>
+    <LazyMonacoEditor {...props} />
+  </Suspense>
+);
+
+// Auto-register with ComponentRegistry
+ComponentRegistry.register('code-editor', CodeEditorRenderer);
+
+// Export for manual integration
+export const editorComponents = {
+  'code-editor': CodeEditorRenderer
+};
+```
+
+### 3. Build Configuration (`vite.config.ts`)
+```typescript
+export default defineConfig({
+  build: {
+    lib: {
+      entry: resolve(__dirname, 'src/index.tsx'),
+      name: 'ObjectUIPluginEditor',
+    },
+    rollupOptions: {
+      // Externalize dependencies
+      external: ['react', 'react-dom', '@object-ui/components', '@object-ui/core'],
+    },
+  },
+});
+```
+
+## Bundle Analysis
+
+### Plugin-Editor Build Output
+```
+dist/index.js                 0.19 kB │ gzip:   0.15 kB
+dist/MonacoImpl-DCiwKyYW.js  19.42 kB │ gzip:   5.89 kB
+dist/index-CpP31686.js       22.42 kB │ gzip:   6.74 kB
+dist/index.umd.cjs           30.37 kB │ gzip:  10.88 kB
+```
+
+### Plugin-Charts Build Output
+```
+dist/index.js                 0.19 kB │ gzip:   0.15 kB
+dist/index-JeMjZMU4.js       22.38 kB │ gzip:   6.69 kB
+dist/ChartImpl-BJBP1UnW.js  541.17 kB │ gzip: 136.04 kB
+dist/index.umd.cjs          393.20 kB │ gzip: 118.97 kB
+```
+
+### Playground Build Output
+When the playground imports both plugins, the chunks are preserved:
+```
+dist/assets/MonacoImpl-DCiwKyYW-D65z0X-D.js     15.26 kB │ gzip:   5.25 kB
+dist/assets/ChartImpl-BJBP1UnW-DO38vX_d.js     348.10 kB │ gzip: 104.54 kB
+dist/assets/index-CyDHUpwF.js                2,212.33 kB │ gzip: 561.16 kB
+```
+
+Notice that:
+- `MonacoImpl` and `ChartImpl` are separate chunks
+- They are NOT included in the main `index.js` bundle
+- They will only be fetched when the components are rendered
+
+## Creating New Lazy-Loaded Plugins
+
+1. **Create the package structure**:
+```bash
+mkdir -p packages/plugin-yourfeature/src
+```
+
+2. **Create the heavy implementation** (`HeavyImpl.tsx`):
+```typescript
+import HeavyLibrary from 'heavy-library';
+
+export default function HeavyImpl(props) {
+  return <HeavyLibrary {...props} />;
+}
+```
+
+3. **Create the lazy wrapper** (`index.tsx`):
+```typescript
+import React, { Suspense } from 'react';
+import { ComponentRegistry } from '@object-ui/core';
+import { Skeleton } from '@object-ui/components';
+
+const LazyComponent = React.lazy(() => import('./HeavyImpl'));
+
+export const YourRenderer = (props) => (
+  <Suspense fallback={<Skeleton />}>
+    <LazyComponent {...props} />
+  </Suspense>
+);
+
+ComponentRegistry.register('your-component', YourRenderer);
+
+export const yourComponents = {
+  'your-component': YourRenderer
+};
+```
+
+4. **Configure build** (`vite.config.ts`):
+```typescript
+import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react';
+
+export default defineConfig({
+  plugins: [react()],
+  build: {
+    lib: {
+      entry: resolve(__dirname, 'src/index.tsx'),
+      name: 'ObjectUIPluginYourFeature',
+    },
+    rollupOptions: {
+      external: ['react', 'react-dom', '@object-ui/components', '@object-ui/core'],
+    },
+  },
+});
+```
+
+5. **Use in the app**:
+```typescript
+// app/src/App.tsx
+import '@object-ui/plugin-yourfeature';
+
+// Now use it in schemas
+const schema = { type: 'your-component', ... };
+```
+
+## Benefits
+
+1. **Smaller Initial Bundle**: Heavy libraries are not included in the main bundle
+2. **Faster Page Loads**: Initial page load only includes essential code
+3. **Better UX**: Components show loading skeletons while chunks download
+4. **Zero Configuration for Users**: The plugin handles all lazy loading internally
+5. **Automatic Code Splitting**: Vite automatically splits the code at build time
+
+## Verification
+
+You can verify lazy loading works by:
+
+1. **Build the playground**:
+```bash
+cd apps/playground
+pnpm build
+ls -lh dist/assets/ | grep -E "(Monaco|Chart)"
+```
+
+2. **Check for separate chunks**:
+```
+MonacoImpl-xxx.js  (~15-20 KB)
+ChartImpl-xxx.js   (~350-540 KB)
+```
+
+3. **Test in browser**:
+- Open DevTools → Network tab
+- Load a page WITHOUT the plugin components
+- The Monaco/Chart chunks should NOT be loaded
+- Navigate to a page WITH the plugin components
+- The chunks should NOW be loaded
+
+## References
+
+- React.lazy() documentation: https://react.dev/reference/react/lazy
+- Vite code splitting: https://vitejs.dev/guide/features.html#code-splitting
+- Rollup chunking: https://rollupjs.org/configuration-options/#output-manualchunks
diff --git a/packages/plugin-charts/README.md b/packages/plugin-charts/README.md
@@ -0,0 +1,102 @@
+# Plugin Charts - Lazy-Loaded Recharts Components
+
+A lazy-loaded charting component for Object UI based on Recharts.
+
+## Features
+
+- **Internal Lazy Loading**: Recharts is loaded on-demand using `React.lazy()` and `Suspense`
+- **Zero Configuration**: Just import the package and use `type: 'chart-bar'` in your schema
+- **Automatic Registration**: Components auto-register with the ComponentRegistry
+- **Skeleton Loading**: Shows a skeleton while Recharts loads
+
+## Installation
+
+```bash
+pnpm add @object-ui/plugin-charts
+```
+
+## Usage
+
+### Automatic Registration (Side-Effect Import)
+
+```typescript
+// In your app entry point (e.g., App.tsx or main.tsx)
+import '@object-ui/plugin-charts';
+
+// Now you can use chart-bar type in your schemas
+const schema = {
+  type: 'chart-bar',
+  data: [
+    { name: 'Jan', value: 400 },
+    { name: 'Feb', value: 300 },
+    { name: 'Mar', value: 600 }
+  ],
+  dataKey: 'value',
+  xAxisKey: 'name',
+  height: 400
+};
+```
+
+### Manual Integration
+
+```typescript
+import { chartComponents } from '@object-ui/plugin-charts';
+import { ComponentRegistry } from '@object-ui/core';
+
+// Manually register if needed
+Object.entries(chartComponents).forEach(([type, component]) => {
+  ComponentRegistry.register(type, component);
+});
+```
+
+## Schema API
+
+```typescript
+{
+  type: 'chart-bar',
+  data?: Array<Record<string, any>>,  // Chart data
+  dataKey?: string,                    // Y-axis data key (default: 'value')
+  xAxisKey?: string,                   // X-axis label key (default: 'name')
+  height?: number,                     // Chart height in pixels (default: 400)
+  color?: string,                      // Bar color (default: '#8884d8')
+  className?: string                   // Tailwind classes
+}
+```
+
+## Lazy Loading Architecture
+
+The plugin uses a two-file pattern for optimal code splitting:
+
+1. **`ChartImpl.tsx`**: Contains the actual Recharts import (heavy ~541 KB)
+2. **`index.tsx`**: Entry point with `React.lazy()` wrapper (light)
+
+When bundled, Vite automatically creates separate chunks:
+- `index.js` (~200 bytes) - The entry point
+- `ChartImpl-xxx.js` (~541 KB minified, ~136 KB gzipped) - The lazy-loaded implementation
+
+The Recharts library is only downloaded when a `chart-bar` component is actually rendered, not on initial page load.
+
+## Build Output Example
+
+```
+dist/index.js                 0.19 kB  # Entry point
+dist/ChartImpl-BJBP1UnW.js  541.17 kB  # Lazy chunk (loaded on demand)
+dist/index.umd.cjs          393.20 kB  # UMD bundle
+```
+
+## Development
+
+```bash
+# Build the plugin
+pnpm build
+
+# The package will generate proper ESM and UMD builds with lazy loading preserved
+```
+
+## Bundle Size Impact
+
+By using lazy loading, the main application bundle stays lean:
+- Without lazy loading: +541 KB on initial load
+- With lazy loading: +0.19 KB on initial load, +541 KB only when chart is rendered
+
+This results in significantly faster initial page loads for applications that don't use charts on every page.
diff --git a/packages/plugin-editor/README.md b/packages/plugin-editor/README.md
