Skip to content

refactor: Migrate plugin loading system from Lit to React #5379

@inureyes

Description

@inureyes

⚠️ Before implementing, read and follow the Implementation Rules in the epic issue #5364. These rules cover mandatory patterns for React component structure, BAI component usage, reactToWebComponent bridge, state management, i18n, error handling, styling, and code quality. The reference implementation is react/src/components/SignupModal.tsx.

Goal: Complete Lit file removal. Each migration must fully replace the Lit source file with React — not just the dialog parts. The migrated Lit .ts file and its type declarations must be deleted. This epic is a critical step toward removing all Lit/MWC/Vaadin dependencies from the codebase.

Description

The current plugin loading system is Lit-based: plugins are discovered from config.toml, dynamically imported as ES modules, instantiated as Lit web components, and appended to the Lit shadow DOM. Post-load management (rendering, routing) is already partially handled by React, but the loading and registration mechanism itself is still in Lit.

This issue migrates the plugin loading pipeline to React while maintaining backward compatibility with existing plugin modules.

Part of epic #5364
Depends on: Navigation consolidation (routing must support dynamic plugin routes)

Current Plugin Loading System

Location: src/components/backend-ai-webui.ts (lines ~500–580)

Flow:

  1. config.toml parsed → config.plugin.page contains plugin URLs
  2. Each plugin URL dynamically imported: import(pluginUrl)
  3. Web component instance created: document.createElement(pluginName)
  4. Plugin appended to #app-page container in Lit shadow DOM
  5. Plugin metadata extracted (menuitem, icon, group) for navigation
  6. backend-ai-plugin-loaded event dispatched

Plugin interface (Lit web component):

  • Extends BackendAIPage (Lit-Element)
  • Exports properties: menuitem, icon, group
  • Renders as standard Lit template

Plugin directories:

  • src/plugin___/, src/plugin_backup/, src/plugins_new/, src/plugins_sample/

Migration Plan

Option A: React Plugin Adapter (Recommended)

Create a React-based plugin loader that can load both legacy Lit plugins (via web component wrapper) and new React plugins.

  1. Create react/src/plugins/PluginLoader.tsx

    • Read plugin configuration from config context/Recoil state
    • Dynamically import plugin modules
    • For Lit plugins: render via web component wrapper
    • For React plugins: render directly as React components
    • Register dynamic routes in React Router
  2. Create plugin metadata system

    • Plugin manifest type: { name, menuitem, icon, group, component }
    • Store in Recoil atom: pluginListState
    • Navigation menu reads from this atom
  3. Create react/src/plugins/PluginPage.tsx

    • Wrapper component that renders a plugin by name
    • Handles loading states and error boundaries
    • Used as route element: <Route path="/plugin/:name" element={<PluginPage />} />

Option B: Direct Migration

If no legacy Lit plugins need to be supported:

  1. Define React plugin interface
  2. Load plugins as React lazy components
  3. Register with React Router directly

Plugin Interface (New React)

interface BackendAIPlugin {
  name: string;
  menuitem: string;
  icon: React.ReactNode;
  group: string;
  component: React.LazyExoticComponent<React.ComponentType>;
}

Acceptance Criteria

  • Plugin loading moved from backend-ai-webui.ts to React
  • Plugins discoverable from config.toml configuration
  • Dynamic route registration works for plugin pages
  • Plugin metadata (menuitem, icon, group) available to React navigation menu
  • Legacy Lit plugins supported via web component wrapper (if needed)
  • New React plugins can be loaded directly
  • backend-ai-plugin-loaded event replaced with React state/callback
  • Error handling for failed plugin loads (error boundary)
  • i18n support in plugins maintained

Metadata

Metadata

Assignees

No one assigned

    Labels

    area:uxUI / UX issue.effort:hardNeed to understand many components / a large extent of contextual or historical information.platform:webWeb-specific issuetype:refactorRefactoring current implementation.

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions