Upgrade to MF v2, and expose UI

[elliotBraem]

Complete Migration Plan

Phase 1: Backend Module Federation v2 Migration

1.1 Update Plugin Template rspack.config.cjs

File: plugins/_template/rspack.config.cjs

const path = require("node:path");
const { ModuleFederationPlugin } = require('@module-federation/enhanced/rspack'); // v2

const pkg = require("./package.json");
const { getNormalizedRemoteName } = require("every-plugin/normalize");
const everyPluginPkg = require("every-plugin/package.json");

function getPluginInfo() {
  return {
    name: pkg.name,
    version: pkg.version,
    normalizedName: getNormalizedRemoteName(pkg.name),
    dependencies: pkg.dependencies || {},
    peerDependencies: pkg.peerDependencies || {},
  };
}

const pluginInfo = getPluginInfo();

module.exports = {
  entry: "./src/index",
  mode: process.env.NODE_ENV === "development" ? "development" : "production",
  target: "async-node",
  devtool: "source-map",
  
  output: {
    uniqueName: pluginInfo.normalizedName,
    publicPath: "auto",
    path: path.resolve(__dirname, "dist"),
    clean: true,
    library: { type: "commonjs-module" },
  },
  
  devServer: {
    static: path.join(__dirname, "dist"),
    hot: true,
    port: 3999,
    devMiddleware: { writeToDisk: true },
  },
  
  module: {
    rules: [
      {
        test: /\.tsx?$/,
        use: "builtin:swc-loader",
        exclude: /node_modules/,
      },
    ],
  },
  
  resolve: {
    extensions: [".tsx", ".ts", ".js"],
  },
  
  plugins: [
    new ModuleFederationPlugin({
      name: pluginInfo.normalizedName,
      filename: "remoteEntry.js",
      
      // v2: Runtime plugins
      runtimePlugins: [
        require.resolve("@module-federation/node/runtimePlugin"),
      ],
      
      library: { type: "commonjs-module" },
      
      exposes: {
        "./plugin": "./src/index.ts",
      },
      
      // v2: Manifest generation
      manifest: {
        fileName: "mf-manifest.json",
        additionalData: async ({ manifest }) => ({
          ...manifest,
          type: "backend",
          target: "node",
          buildTime: new Date().toISOString(),
          gitCommit: process.env.GIT_COMMIT,
        }),
      },
      
      // v2: TypeScript types
      dts: {
        tsConfigPath: "./tsconfig.json",
        generateTypes: {
          compiledTypesFolder: "compiled-types",
          typesFolder: "@mf-types",
          deleteTypesFolder: true,
          extractThirdParty: false,
          extractRemoteTypes: false, // Backend doesn't need remote types
        },
      },
      
      // v2: Share strategy
      shareStrategy: "loaded-first",
      
      shared: {
        "every-plugin": {
          version: everyPluginPkg.version,
          singleton: true,
          requiredVersion: everyPluginPkg.version,
          strictVersion: false,
          eager: false,
        },
        effect: {
          version: everyPluginPkg.dependencies.effect,
          singleton: true,
          requiredVersion: everyPluginPkg.dependencies.effect,
          strictVersion: false,
          eager: false,
        },
        zod: {
          version: everyPluginPkg.dependencies.zod,
          singleton: true,
          requiredVersion: everyPluginPkg.dependencies.zod,
          strictVersion: false,
          eager: false,
        },
        "@orpc/contract": {
          version: everyPluginPkg.dependencies["@orpc/contract"],
          singleton: true,
          requiredVersion: everyPluginPkg.dependencies["@orpc/contract"],
          strictVersion: false,
          eager: false,
        },
        "@orpc/server": {
          version: everyPluginPkg.dependencies["@orpc/server"],
          singleton: true,
          requiredVersion: everyPluginPkg.dependencies["@orpc/server"],
          strictVersion: false,
          eager: false,
        },
      },
    }),
  ],
};

1.2 Update normalizeRemoteUrl (Manifest Support)

File: packages/core/src/runtime/index.ts

/**
 * Normalizes a remote URL to ensure it points to mf-manifest.json (v2) or remoteEntry.js (v1)
 */
function normalizeRemoteUrl(url: string): string {
  // If already points to a file, keep it
  if (url.endsWith('.json') || url.endsWith('.js')) return url;
  
  // v2: Default to manifest
  return `${url.endsWith('/') ? url.slice(0, -1) : url}/mf-manifest.json`;
}

Phase 2: Client Runtime for Browser UI

2.1 Create Lightweight Client Runtime

File: packages/core/src/runtime/client.ts

import { createORPCClient } from "@orpc/client";
import { RPCLink } from "@orpc/client/fetch";
import type { RouterClient } from "@orpc/server";
import { init, loadRemote } from "@module-federation/enhanced/runtime";
import type { PluginRegistry, RegisteredPlugins } from "../types";

export interface ClientRuntimeConfig {
  registry: {
    [K in keyof RegisteredPlugins]: {
      remoteUrl: string;  // Backend manifest
      version: string;
      ui?: {
        remoteUrl: string;  // Frontend manifest
        version: string;
      };
    };
  };
  rpcEndpoint: string;  // Base URL where plugin routers are mounted
}

export interface UIPluginComponents<K extends keyof RegisteredPlugins> {
  // Components will be discovered from manifest
  [componentName: string]: React.ComponentType<any>;
}

export interface UsePluginUIResult<K extends keyof RegisteredPlugins> {
  components: UIPluginComponents<K>;
  rpcClient: RouterClient<RegisteredPlugins[K]["binding"]["contract"]>;
  metadata: {
    id: string;
    version: string;
    manifest: any;
  };
}

export class ClientRuntime {
  private mfInstance: ReturnType<typeof init>;
  private componentCache = new Map<string, any>();
  private rpcClientCache = new Map<string, any>();
  
  constructor(private config: ClientRuntimeConfig) {
    // Initialize Module Federation for browser
    this.mfInstance = init({
      name: "ui_host",
      remotes: Object.entries(config.registry)
        .filter(([_, entry]) => entry.ui) 
        .map(([name, entry]) => ({
          name: `${name}_ui`,
          entry: entry.ui!.remoteUrl,
          alias: name,
        })),
      shared: {
        react: { singleton: true, requiredVersion: "^18.0.0" },
        "react-dom": { singleton: true, requiredVersion: "^18.0.0" },
      },
    });
  }
  
  async usePlugin<K extends keyof RegisteredPlugins & string>(
    pluginId: K
  ): Promise<UsePluginUIResult<K>> {
    const entry = this.config.registry[pluginId];
    
    if (!entry.ui) {
      throw new Error(`Plugin ${pluginId} does not expose UI components`);
    }
    
    // Fetch manifest to discover components
    const manifestResponse = await fetch(entry.ui.remoteUrl);
    const manifest = await manifestResponse.json();
    
    const componentMeta = manifest.components || {};
    
    // Create lazy loaders for all components
    const components: any = {};
    
    for (const [name, meta] of Object.entries(componentMeta) as [string, any][]) {
      const componentKey = `${pluginId}/${name}`;
      
      if (!this.componentCache.has(componentKey)) {
        // Use React.lazy pattern
        const LazyComponent = React.lazy(() =>
          loadRemote<{ default: React.ComponentType<any> }>(`${pluginId}/${name}`)
        );
        this.componentCache.set(componentKey, LazyComponent);
      }
      
      components[name] = this.componentCache.get(componentKey);
    }
    
    // Create RPC client for backend communication
    const rpcPath = `${this.config.rpcEndpoint}/${pluginId}`;
    
    if (!this.rpcClientCache.has(pluginId)) {
      const link = new RPCLink({
        url: rpcPath,
        fetch: globalThis.fetch,
      });
      
      const client = createORPCClient(link);
      this.rpcClientCache.set(pluginId, client);
    }
    
    return {
      components,
      rpcClient: this.rpcClientCache.get(pluginId)!,
      metadata: {
        id: pluginId,
        version: entry.ui.version,
        manifest,
      },
    };
  }
}

/**
 * Create a lightweight runtime for browser UI
 * Does NOT use Effect/ManagedRuntime - pure Module Federation
 */
export function createClientRuntime(
  config: ClientRuntimeConfig
): ClientRuntime {
  return new ClientRuntime(config);
}

2.2 Export from main package

File: packages/core/src/index.ts

// Add to exports
export { createClientRuntime, type ClientRuntimeConfig, type UsePluginUIResult } from "./runtime/client";

File: packages/core/package.json - Add export

{
  "exports": {
    "./runtime/client": {
      "types": "./dist/runtime/client.d.ts",
      "default": "./dist/runtime/client.js"
    }
  }
}

Phase 3: Plugin UI Build Structure

3.1 Create UI Template Structure

New Directory: plugins/_template/ui/

plugins/_template/ui/
├── src/
│   ├── main.tsx
│   ├── components/
│   │   ├── Dashboard.tsx
│   │   └── Settings.tsx
│   └── lib/
│       └── rpc-client.ts
├── rspack.config.js
├── package.json
└── tsconfig.json

3.2 UI Build Config

File: plugins/_template/ui/rspack.config.js

const { ModuleFederationPlugin } = require('@module-federation/enhanced/rspack');
const path = require('path');

const parentPkg = require('../package.json');

module.exports = {
  target: 'web',
  entry: './src/main.tsx',
  
  output: {
    path: path.resolve(__dirname, 'dist'),
    publicPath: 'http://localhost:3100/',  // Different port for UI
    clean: true,
  },
  
  module: {
    rules: [
      {
        test: /\.tsx?$/,
        use: 'builtin:swc-loader',
        exclude: /node_modules/,
      },
      {
        test: /\.css$/,
        use: ['style-loader', 'css-loader'],
      },
    ],
  },
  
  resolve: {
    extensions: ['.tsx', '.ts', '.js'],
  },
  
  plugins: [
    new ModuleFederationPlugin({
      name: `${parentPkg.name.replace(/[@\/]/g, '_')}_ui`,
      
      exposes: {
        './Dashboard': './src/components/Dashboard',
        './Settings': './src/components/Settings',
      },
      
      manifest: {
        fileName: 'mf-manifest.json',
        additionalData: async ({ manifest }) => ({
          ...manifest,
          type: 'frontend',
          target: 'web',
          framework: 'react',
          components: {
            Dashboard: {
              path: './Dashboard',
              description: 'Main dashboard view',
            },
            Settings: {
              path: './Settings',
              description: 'Plugin settings panel',
            },
          },
        }),
      },
      
      shared: {
        react: { singleton: true, requiredVersion: '^18.0.0' },
        'react-dom': { singleton: true, requiredVersion: '^18.0.0' },
      },
    }),
  ],
  
  devServer: {
    port: 3100,
    hot: true,
    headers: {
      'Access-Control-Allow-Origin': '*',
    },
  },
};

3.3 Update Parent Scripts

File: plugins/_template/package.json

{
  "scripts": {
    "dev": "concurrently \"npm run dev:backend\" \"npm run dev:ui\"",
    "dev:backend": "rspack serve --config rspack.config.cjs --port 3999",
    "dev:ui": "cd ui && rspack serve --port 3100",
    
    "build": "npm run build:backend && npm run build:ui",
    "build:backend": "rspack build --config rspack.config.cjs",
    "build:ui": "cd ui && rspack build"
  },
  "devDependencies": {
    "concurrently": "^9.0.0"
  }
}

Phase 4: Registry & Type Updates

4.1 Enhanced Registry Type

File: packages/core/src/types.ts

export interface PluginRegistryEntry {
  remoteUrl: string;  // Backend manifest URL
  version: string;
  ui?: {
    remoteUrl: string;  // Frontend manifest URL  
    version: string;
  };
}

export type PluginRegistry = Record<string, PluginRegistryEntry>;

4.2 Update createPluginRuntime

File: packages/core/src/runtime/index.ts

function normalizeRemoteUrl(url: string): string {
  if (url.endsWith('.json') || url.endsWith('.js')) return url;
  // v2: Default to manifest
  return `${url.endsWith('/') ? url.slice(0, -1) : url}/mf-manifest.json`;
}

export function createPluginRuntime(
  config: PluginRuntimeConfig
): PluginRuntime {
  const secrets = config.secrets || {};

  // Normalize backend URLs only
  const normalizedRegistry = Object.fromEntries(
    Object.entries(config.registry).map(([pluginId, entry]) => [
      pluginId,
      {
        ...entry,
        remoteUrl: normalizeRemoteUrl(entry.remoteUrl),
        // Keep UI remoteUrl as-is if present
        ...(entry.ui && {
          ui: {
            ...entry.ui,
            remoteUrl: normalizeRemoteUrl(entry.ui.remoteUrl),
          },
        }),
      },
    ])
  ) as PluginRegistry;

  const layer = PluginService.Live(normalizedRegistry, secrets);
  const runtime = Managed

Runtime.make(layer);

  return new PluginRuntime(runtime, normalizedRegistry);
}

Phase 5: Example Implementation

5.1 Update Example Registry

File: examples/curatedotfun/plugins.ts

import type GopherAIPlugin from "@curatedotfun/gopher-ai";
import { createPluginRuntime } from "every-plugin/runtime";

declare module "every-plugin" {
  interface RegisteredPlugins {
    "@curatedotfun/gopher-ai": typeof GopherAIPlugin;
  }
}

export const runtime = createPluginRuntime({
  registry: {
    "@curatedotfun/gopher-ai": {
      // v2: Manifest URL instead of remoteEntry.js
      remoteUrl: "https://elliot-braem-159-curatedotfun-gopher-ai-every-plu-bf7adf22c-ze.zephyrcloud.app/mf-manifest.json",
      version: "1.0.0",
      
      // NEW: UI manifest (if plugin has UI)
      ui: {
        remoteUrl: "https://elliot-braem-159-curatedotfun-gopher-ai-ui-bf7adf22c-ze.zephyrcloud.app/mf-manifest.json",
        version: "1.0.0"
      }
    }
  },
  secrets: {
    GOPHERAI_API_KEY: Bun.env.GOPHERAI_API_KEY || "your-masa-api-key-here"
  }
});

// Backend plugin initialization (unchanged)
const gopherAi = await runtime.usePlugin(
  "@curatedotfun/gopher-ai",
  {
    secrets: { apiKey: "{{GOPHERAI_API_KEY}}" },
    variables: { baseUrl: "https://data.gopher-ai.com/api/v1", timeout: 30000 }
  }
);

export const plugins = {
  gopherAi
};

5.2 Create Frontend Example

New File: examples/curatedotfun-ui/app.tsx

import { createClientRuntime } from "every-plugin/runtime/client";
import { Suspense } from "react";

const clientRuntime = createClientRuntime({
  registry: {
    "@curatedotfun/gopher-ai": {
      remoteUrl: "https://...backend.../mf-manifest.json",
      version: "1.0.0",
      ui: {
        remoteUrl: "https://...frontend.../mf-manifest.json",
        version: "1.0.0"
      }
    }
  },
  rpcEndpoint: "http://localhost:3000/api"  // Where backend router is mounted
});

export function App() {
  const [plugin, setPlugin] = useState<any>(null);
  
  useEffect(() => {
    clientRuntime.usePlugin("@curatedotfun/gopher-ai").then(setPlugin);
  }, []);
  
  if (!plugin) return <div>Loading...</div>;
  
  const { components, rpcClient } = plugin;
  const Dashboard = components.Dashboard;
  
  return (
    <Suspense fallback={<div>Loading component...</div>}>
      <Dashboard rpcClient={rpcClient} />
    </Suspense>
  );
}

Phase 6: Testing Updates

6.1 Update Test Fixtures

File: packages/core/tests/fixtures/test-plugin/rspack.config.cjs

Apply same v2 changes as template (manifest, dts, shareStrategy, etc.)

6.2 Add Client Runtime Tests

New File: packages/core/tests/unit/client-runtime.test.ts

import { createClientRuntime } from "every-plugin/runtime/client";
import { beforeAll, describe, expect, it } from "vitest";

describe("ClientRuntime", () => {
  it("should initialize without Effect dependencies", () => {
    const runtime = createClientRuntime({
      registry: {
        "test-plugin": {
          remoteUrl: "http://localhost:3999/mf-manifest.json",
          version: "1.0.0",
          ui: {
            remoteUrl: "http://localhost:3100/mf-manifest.json",
            version: "1.0.0"
          }
        }
      },
      rpcEndpoint: "http://localhost:3000/api"
    });
    
    expect(runtime).toBeDefined();
  });
  
  // More tests for component loading, RPC client creation, etc.
});

Phase 7: Documentation Updates

7.1 Update LLM.txt

Add section on UI builds and client runtime

7.2 Update docs/index.mdx

Add UI component section

Conflicts Analysis

No major conflicts detected, but considerations:

1. Module Federation services remain Node-only - Client runtime bypasses them entirely
2. Shared packages are correct - Client doesn't need @orpc/server or Effect services
3. Cache separation - Client runtime has its own caches, independent of server
4. Port management - Backend (3999) and UI (3100) use different ports

Migration Checklist

• Update all plugin rspack configs to v2
• Change remoteUrl to manifest URLs in registries
• Add manifest generation config
• Add dts config for TypeScript
• Add shareStrategy: "loaded-first"
• Create ui/ directory in plugins that need UI
• Implement client runtime (lightweight, no Effect)
• Add UI build scripts
• Update examples
• Add client runtime tests
• Update documentation

This plan maintains backward compatibility while adding v2 features incrementally!

[elliotBraem]

Excellent questions! Let me address each concern with enhanced solutions:

1. Effect.TS Integration & Resource Management

Current Issue: The ClientRuntime doesn't use Effect, which feels inconsistent with the rest of your codebase. Also potential resource leaks from component/RPC client caches.

Solution: Create an Effect-wrapped version that provides proper lifecycle management:

// packages/core/src/runtime/client.ts

import { Effect, Layer, Ref } from "effect";
import type { Scope } from "effect";

export class ClientRuntimeService extends Effect.Service<ClientRuntimeService>()("ClientRuntimeService", {
  scoped: Effect.gen(function* () {
    const config = yield* ClientRuntimeConfig;
    const componentCache = yield* Ref.make(new Map<string, any>());
    const rpcClientCache = yield* Ref.make(new Map<string, any>());
    
    // Initialize Module Federation with cleanup
    const mfInstance = yield* Effect.acquireRelease(
      Effect.sync(() => init({
        name: "ui_host",
        remotes: Object.entries(config.registry)
          .filter(([_, entry]) => entry.ui)
          .map(([name, entry]) => ({
            name: `${name}_ui`,
            entry: entry.ui!.remoteUrl,
            alias: name,
          })),
        shared: {
          react: { singleton: true, requiredVersion: "^18.0.0" },
          "react-dom": { singleton: true, requiredVersion: "^18.0.0" },
        },
      })),
      // Cleanup: clear all caches
      () => Effect.gen(function* () {
        yield* Ref.set(componentCache, new Map());
        yield* Ref.set(rpcClientCache, new Map());
      })
    );
    
    return {
      usePlugin: <K extends keyof RegisteredPlugins & string>(pluginId: K) =>
        Effect.gen(function* () {
          const entry = config.registry[pluginId];
          
          if (!entry.ui) {
            return yield* Effect.fail(
              new Error(`Plugin ${pluginId} does not expose UI components`)
            );
          }
          
          // Fetch manifest with proper error handling
          const manifest = yield* Effect.tryPromise({
            try: () => fetch(entry.ui!.remoteUrl).then(r => r.json()),
            catch: (error) => new Error(`Failed to fetch UI manifest: ${error}`)
          });
          
          const componentMeta = manifest.components || {};
          const components: any = {};
          
          // Load components with caching
          const currentCache = yield* Ref.get(componentCache);
          
          for (const [name, meta] of Object.entries(componentMeta) as [string, any][]) {
            const componentKey = `${pluginId}/${name}`;
            
            if (!currentCache.has(componentKey)) {
              const LazyComponent = React.lazy(() =>
                loadRemote<{ default: React.ComponentType<any> }>(`${pluginId}/${name}`)
              );
              
              yield* Ref.update(componentCache, cache => {
                const newCache = new Map(cache);
                newCache.set(componentKey, LazyComponent);
                return newCache;
              });
            }
            
            components[name] = currentCache.get(componentKey);
          }
          
          // Create RPC client with caching
          const currentRpcCache = yield* Ref.get(rpcClientCache);
          
          if (!currentRpcCache.has(pluginId)) {
            const link = new RPCLink({
              url: `${config.rpcEndpoint}/${pluginId}`,
              fetch: globalThis.fetch,
            });
            
            const client = createORPCClient(link);
            
            yield* Ref.update(rpcClientCache, cache => {
              const newCache = new Map(cache);
              newCache.set(pluginId, client);
              return newCache;
            });
          }
          
          return {
            components,
            rpcClient: currentRpcCache.get(pluginId)!,
            metadata: {
              id: pluginId,
              version: entry.ui.version,
              manifest,
            },
          };
        }),
    };
  }),
}) {}

// Lightweight version for those who don't want Effect
export class ClientRuntime {
  // Original implementation without Effect
}

export function createClientRuntime(config: ClientRuntimeConfig): ClientRuntime {
  return new ClientRuntime(config);
}

// Effect-based version with proper resource management
export const ClientRuntimeLayer = Layer.effect(
  ClientRuntimeService,
  Effect.gen(function* () {
    // Service implementation
  })
);

No resource leaks - Effect's scoped lifecycle ensures cleanup!

2. Centralized Config & Rspack vs Rsbuild (continued)

Create centralized plugin.config.ts:

// plugins/my-plugin/plugin.config.ts

import { definePluginConfig } from "every-plugin/config";

export default definePluginConfig({
  name: "my-plugin",
  version: "1.0.0",
  
  // Backend configuration
  backend: {
    port: 3014,
    target: "async-node",
    exposes: {
      "./plugin": "./src/index.ts"
    }
  },
  
  // Frontend configuration (optional)
  ui: {
    port: 3015,
    framework: "react", // or "vue", "svelte"
    exposes: {
      Dashboard: {
        path: "./src/components/Dashboard",
        description: "Main dashboard view"
      },
      Settings: {
        path: "./src/components/Settings",
        description: "Settings panel"
      }
    }
  },
  
  // Shared dependencies (auto-merged with every-plugin defaults)
  shared: {
    // Custom shared deps beyond defaults
  }
});

Auto-generate both configs:

// packages/core/src/config/index.ts

export function definePluginConfig(config: PluginConfig) {
  return config;
}

// Generate rspack config for backend
export function generateBackendConfig(pluginConfig: PluginConfig) {
  const { ModuleFederationPlugin } = require('@module-federation/enhanced/rspack');
  const everyPluginPkg = require('every-plugin/package.json');
  
  return {
    target: 'async-node',
    entry: './src/index',
    
    output: {
      path: path.resolve(process.cwd(), 'dist'),
      library: { type: 'commonjs-module' }
    },
    
    plugins: [
      new ModuleFederationPlugin({
        name: pluginConfig.name,
        exposes: pluginConfig.backend.exposes,
        
        manifest: {
          fileName: 'mf-manifest.json',
          additionalData: {
            type: 'backend',
            target: 'node',
            version: pluginConfig.version
          }
        },
        
        dts: {
          tsConfigPath: './tsconfig.json',
          generateTypes: true,
        },
        
        runtimePlugins: [
          require.resolve('@module-federation/node/runtimePlugin')
        ],
        
        shared: mergeShared(defaultShared, pluginConfig.shared)
      })
    ],
    
    devServer: {
      port: pluginConfig.backend.port
    }
  };
}

// Generate rsbuild config for frontend
export function generateUIConfig(pluginConfig: PluginConfig) {
  const { defineConfig } = require('@rsbuild/core');
  const { pluginReact } = require('@rsbuild/plugin-react');
  const { pluginModuleFederation } = require('@module-federation/rsbuild-plugin');
  
  return defineConfig({
    server: {
      port: pluginConfig.ui!.port
    },
    
    plugins: [
      pluginReact(),
      
      pluginModuleFederation({
        name: `${pluginConfig.name}_ui`,
        
        exposes: Object.fromEntries(
          Object.entries(pluginConfig.ui!.exposes).map(([name, config]) => [
            `./${name}`,
            config.path
          ])
        ),
        
        manifest: {
          fileName: 'mf-manifest.json',
          additionalData: {
            type: 'frontend',
            target: 'web',
            framework: pluginConfig.ui!.framework,
            version: pluginConfig.version,
            components: pluginConfig.ui!.exposes
          }
        },
        
        shared: {
          react: { singleton: true },
          'react-dom': { singleton: true }
        }
      })
    ]
  });
}

Simplified plugin structure:

// plugins/my-plugin/rspack.config.cjs (backend)
const { generateBackendConfig } = require('every-plugin/config');
const pluginConfig = require('./plugin.config');

module.exports = generateBackendConfig(pluginConfig);

// plugins/my-plugin/ui/rsbuild.config.ts (frontend)
import { generateUIConfig } from 'every-plugin/config';
import pluginConfig from '../plugin.config';

export default generateUIConfig(pluginConfig);

Benefits:

• Single source of truth
• No manual rspack configuration
• Automatic best practices
• Easy to update framework-wide

3. Automatic Type Generation with DTS

The problem you're solving is HUGE! Let me show you how v2's dts feature eliminates the need for manual module augmentation:

Current (Manual) Flow:

// 1. Install plugin as devDep
npm install -D @my-org/my-plugin

// 2. Manual augmentation in every consumer
declare module "every-plugin" {
  interface RegisteredPlugins {
    "@my-org/my-plugin": typeof import("@my-org/my-plugin").default;
  }
}

New (Automatic) Flow with DTS:

Plugin Side (One-time setup):

// plugins/my-plugin/rspack.config.cjs
new ModuleFederationPlugin({
  name: 'my_plugin',
  
  dts: {
    tsConfigPath: './tsconfig.json',
    generateTypes: {
      compiledTypesFolder: 'compiled-types',
      typesFolder: '@mf-types',        // Generated types location
      deleteTypesFolder: true,
      extractThirdParty: true,          // Include dependency types
      extractRemoteTypes: true,         // ← KEY: Generate consumable types
    },
    consumeTypes: {
      remoteTypesFolder: '@mf-types',
      maxRetries: 3,
      timeout: 5000
    }
  },
  
  manifest: {
    fileName: 'mf-manifest.json',
    additionalData: async ({ manifest }) => ({
      ...manifest,
      // Include types location in manifest
      types: {
        entry: '@mf-types/index.d.ts',
        remote: true
      }
    })
  }
})

Consumer Side (Automatic):

// Host app rspack/rsbuild config
new ModuleFederationPlugin({
  name: 'host',
  
  remotes: {
    'my-plugin': 'my_plugin@http://localhost:3014/mf-manifest.json'
  },
  
  dts: {
    consumeTypes: {
      remoteTypesFolder: '@mf-types',  // Where to download remote types
      automaticTyping: true,           // Auto-fetch from manifest
      maxRetries: 3
    }
  }
})

Result: Zero manual work!

// In host app - types work automatically!
const { client } = await runtime.usePlugin("my-plugin", config);

// Full autocomplete, no manual augmentation needed!
client.getData({ id: "test" });  // ✅ Types just work

Enhanced Type System for Registry

Create automatic type discovery:

// packages/core/src/types.ts - Enhanced

/**
 * Auto-discover types from @mf-types directory
 */
type DiscoverMFTypes<K extends string> = K extends keyof RegisteredPlugins
  ? RegisteredPlugins[K]
  : K extends `@${infer Org}/${infer Name}`
    ? import(`@mf-types/${Org}_${Name}/index`).default
    : never;

/**
 * Smart plugin type resolution
 */
export type ResolvePlugin<K extends string> =
  K extends keyof RegisteredPlugins
    ? RegisteredPlugins[K]
    : DiscoverMFTypes<K>;

/**
 * Enhanced usePlugin with auto-discovery
 */
export interface EnhancedPluginRuntime {
  usePlugin<K extends string>(
    pluginId: K,
    config: PluginConfigInput<ResolvePlugin<K>>
  ): Promise<UsePluginResult<K>>;
}

Generate type bridge automatically:

// packages/core/src/config/type-bridge.ts

export function generateTypeBridge(manifest: any) {
  const typesUrl = manifest.types?.entry;
  
  if (!typesUrl) return;
  
  // Download types from CDN
  const types = await fetch(`${manifest.publicPath}${typesUrl}`).then(r => r.text());
  
  // Write to @mf-types directory
  const pluginTyp


## 🎯 Complete Implementation Checklist

### Phase 1: Core Infrastructure (Foundation)

#### 1.1 Package Updates
- [ ] Update `packages/core/package.json` dependencies:
  - [ ] `@module-federation/enhanced` to latest v2
  - [ ] Add `@rsbuild/core`, `@rsbuild/plugin-react`
  - [ ] Add `@module-federation/rsbuild-plugin`
- [ ] Add new exports to `packages/core/package.json`:
  - [ ] `./runtime/client` 
  - [ ] `./config`
- [ ] Update `packages/core/src/index.ts` with new exports

#### 1.2 Type System Enhancements
- [ ] Update `packages/core/src/types.ts`:
  - [ ] Add `PluginRegistryEntry` with `ui` property
  - [ ] Add `DiscoverMFTypes` for automatic type discovery
  - [ ] Add `ResolvePlugin` helper
  - [ ] Add `UIPluginComponents` type
  - [ ] Add `ClientRuntimeConfig` interface

#### 1.3 Client Runtime (Effect-Based)
- [ ] Create `packages/core/src/runtime/client.ts`:
  - [ ] `ClientRuntimeService` with Effect lifecycle
  - [ ] Scoped resource management for MF instance
  - [ ] Component cache with `Ref`
  - [ ] RPC client cache with `Ref`
  - [ ] `usePlugin` method with proper error handling
  - [ ] Lightweight `ClientRuntime` class (non-Effect version)
  - [ ] Export layer for composition

#### 1.4 Configuration System
- [ ] Create `packages/core/src/config/index.ts`:
  - [ ] `definePluginConfig` helper
  - [ ] `PluginConfig` interface
  - [ ] `generateBackendConfig` for rspack
  - [ ] `generateUIConfig` for rsbuild
  - [ ] `mergeShared` utility for dependencies
  - [ ] `defaultShared` configuration object

#### 1.5 Type Bridge Generator
- [ ] Create `packages/core/src/config/type-bridge.ts`:
  - [ ] Fetch types from manifest
  - [ ] Write to `@mf-types` directory
  - [ ] Generate augmentation file
  - [ ] Cache management

### Phase 2: Backend Migration (Module Federation v2)

#### 2.1 Update Core Runtime
- [ ] Update `packages/core/src/runtime/index.ts`:
  - [ ] Enhance `normalizeRemoteUrl` for manifests
  - [ ] Update `createPluginRuntime` to handle UI manifests
  - [ ] Add support for `PluginRegistryEntry` type

#### 2.2 Update Module Federation Service
- [ ] Update `packages/core/src/runtime/services/module-federation.service.ts`:
  - [ ] Add `@orpc/experimental-publisher` to shared deps
  - [ ] Update shared config with correct versions
  - [ ] Support manifest URLs in `registerRemote`

#### 2.3 Plugin Template v2
- [ ] Update `plugins/_template/rspack.config.cjs`:
  - [ ] Use `@module-federation/enhanced/rspack`
  - [ ] Add `manifest` generation config
  - [ ] Add `dts` type generation config
  - [ ] Add `runtimePlugins` for Node.js
  - [ ] Update `shareStrategy` to "loaded-first"
  - [ ] Remove old `@rspack/core` imports

#### 2.4 Update Test Plugin
- [ ] Update `packages/core/tests/fixtures/test-plugin/rspack.config.cjs`
  - [ ] Apply same v2 changes as template
  - [ ] Ensure test compatibility

### Phase 3: UI Support (Frontend Components)

#### 3.1 UI Template Structure
- [ ] Create `plugins/_template/ui/` directory
- [ ] Create `plugins/_template/ui/package.json`
- [ ] Create `plugins/_template/ui/tsconfig.json`
- [ ] Create `plugins/_template/ui/rsbuild.config.ts`
- [ ] Create `plugins/_template/ui/src/main.tsx`
- [ ] Create `plugins/_template/ui/src/components/Dashboard.tsx`
- [ ] Create `plugins/_template/ui/src/components/Settings.tsx`
- [ ] Create `plugins/_template/ui/src/lib/rpc-client.ts` (typed RPC helper)

#### 3.2 Default UI Components
- [ ] Create base component interfaces in `packages/core/src/ui/`:
  - [ ] `PluginDashboard` interface
  - [ ] `PluginSettings` interface
  - [ ] Default fallback components
- [ ] Add UI metadata to plugin config schema
- [ ] Support component overrides in `usePlugin`

#### 3.3 Update Plugin Template Config
- [ ] Create `plugins/_template/plugin.config.ts`
- [ ] Update `plugins/_template/package.json` scripts:
  - [ ] `dev` - run both backend & UI
  - [ ] `dev:backend` - rspack backend
  - [ ] `dev:ui` - rsbuild frontend
  - [ ] `build` - build both
  - [ ] `build:backend`
  - [ ] `build:ui`
- [ ] Add `concurrently` to devDependencies

### Phase 4: Enhanced Examples

#### 4.1 Update Existing Example
- [ ] Update `examples/curatedotfun/plugins.ts`:
  - [ ] Change to manifest URLs
  - [ ] Add `ui` property to registry entries
- [ ] Keep backend example working as-is

#### 4.2 Create UI Example
- [ ] Create `examples/curatedotfun-ui/` directory
- [ ] Create React app with TanStack Router
- [ ] Demonstrate `createClientRuntime` usage
- [ ] Show component loading with Suspense
- [ ] Show RPC client usage from UI
- [ ] Add example of component overrides

#### 4.3 Full-Stack Integration Example
- [ ] Create `examples/full-stack-plugin/`:
  - [ ] Backend + UI in single plugin
  - [ ] Shared types between backend and frontend
  - [ ] RPC communication examples
  - [ ] Streaming data to UI components

### Phase 5: Testing

#### 5.1 Unit Tests
- [ ] Create `packages/core/tests/unit/client-runtime.test.ts`
  - [ ] Test ClientRuntime initialization
  - [ ] Test component loading
  - [ ] Test RPC client creation
  - [ ] Test caching behavior
- [ ] Create `packages/core/tests/unit/config-generation.test.ts`
  - [ ] Test backend config generation
  - [ ] Test UI config generation
  - [ ] Test shared dependency merging

#### 5.2 Integration Tests
- [ ] Update `packages/core/tests/integration/` tests for v2
- [ ] Add UI component loading tests
- [ ] Add manifest parsing tests
- [ ] Add type generation tests

#### 5.3 E2E Tests
- [ ] Create `packages/core/tests/e2e/full-stack.test.ts`
  - [ ] Start backend plugin
  - [ ] Start UI plugin
  - [ ] Load components in browser
  - [ ] Test RPC communication
  - [ ] Test streaming

### Phase 6: Documentation

#### 6.1 Core Docs
- [ ] Update `apps/docs/content/docs/index.mdx`:
  - [ ] Add UI components section
  - [ ] Update quick start with v2
  - [ ] Add manifest benefits
- [ ] Update `apps/docs/content/docs/creating-plugins/`:
  - [ ] Add UI components guide
  - [ ] Add configuration guide
  - [ ] Update build process docs

#### 6.2 Technical Docs
- [ ] Update `plugins/_template/LLM.txt`:
  - [ ] Add UI component section
  - [ ] Add configuration section
  - [ ] Add automatic types section
  - [ ] Update Module Federation to v2
- [ ] Create `apps/docs/content/docs/ui-components.mdx`
- [ ] Create `apps/docs/content/docs/configuration.mdx`

#### 6.3 Migration Guide
- [ ] Create `apps/docs/content/docs/migration/v1-to-v2.mdx`:
  - [ ] Step-by-step migration
  - [ ] Breaking changes
  - [ ] Benefits overview
  - [ ] Troubleshooting

#### 6.4 API Reference
- [ ] Document `createClientRuntime`
- [ ] Document `definePluginConfig`
- [ ] Document `ClientRuntimeService`
- [ ] Document automatic type generation

### Phase 7: Developer Experience

#### 7.1 CLI Enhancements
- [ ] Add to `packages/cli/`:
  - [ ] `create-plugin` scaffold with UI option
  - [ ] `add-ui` command for existing plugins
  - [ ] `migrate-v2` command for automatic migration

#### 7.2 Tooling
- [ ] Create ESLint rules for plugin structure
- [ ] Add VSCode snippets for plugin creation
- [ ] Add debug configurations

### Phase 8: Real Plugin Migration

#### 8.1 Migrate Test Plugin
- [ ] Migrate `packages/core/tests/fixtures/test-plugin` to full v2
- [ ] Add UI components to test plugin
- [ ] Verify all tests pass

#### 8.2 Migrate Example Plugins
- [ ] Migrate `plugins/gopher-ai` to v2
- [ ] Add UI components to gopher-ai
- [ ] Migrate `plugins/telegram` to v2

### Phase 9: Polish & Performance

#### 9.1 Optimization
- [ ] Add bundle analyzer to UI builds
- [ ] Optimize shared dependencies
- [ ] Add component lazy-loading tests
- [ ] Measure and optimize startup time

#### 9.2 Error Handling
- [ ] Add comprehensive error boundaries
- [ ] Add retry logic for manifest fetching
- [ ] Add fallback UI for failed components
- [ ] Add detailed error messages

#### 9.3 DevTools
- [ ] Create browser extension for debugging
  - [ ] Show loaded plugins
  - [ ] Show component tree
  - [ ] Show RPC calls
  - [ ] Show manifest info

### Phase 10: Release Preparation

#### 10.1 Version Updates
- [ ] Update all package versions to 0