@xema-platform/plugin-host-react-router

Drop-in HostBridge implementation and route-mounting helpers for React frontends that use react-router-dom. Wraps the host's existing router, auth client, toast library, and react-query QueryClient into the shell-agnostic HostBridge contract from @xema-platform/plugin-registry-web — so plugin authors never need to touch react-router (or any other host-specific primitive) directly.

Install

npm install @xema-platform/plugin-host-react-router @xema-platform/plugin-registry-web
# or
pnpm add @xema-platform/plugin-host-react-router @xema-platform/plugin-registry-web

react, react-router-dom, and @tanstack/react-query are peer dependencies — your host already has them.

Quick start

import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
import { BrowserRouter, Routes, Route } from 'react-router-dom';
import {
  DefaultHostBridgeProvider,
  mountPluginRoutes,
  mergeNavSections,
} from '@xema-platform/plugin-host-react-router';

const queryClient = new QueryClient();

function App() {
  return (
    <QueryClientProvider client={queryClient}>
      <BrowserRouter>
        <DefaultHostBridgeProvider
          auth={{
            getActorToken: () => keycloak.token ?? null,
            getOrgId: () => currentOrgId,
            getProjectId: () => readProjectIdFromUrl(),
            getUserId: () => keycloak.tokenParsed?.sub ?? null,
          }}
          toast={{
            success: (msg) => myToastLib.success(msg),
            error: (msg, detail) => myToastLib.error(msg, { description: detail }),
            info: (msg) => myToastLib.info(msg),
          }}
          queryClient={queryClient}
        >
          <Routes>
            <Route path="/" element={<HomePage />} />
            {mountPluginRoutes({ projectScoped: false })}
            <Route path="/projects/:projectId/*" element={<ProjectLayout />}>
              {mountPluginRoutes({ projectScoped: true })}
            </Route>
          </Routes>
        </DefaultHostBridgeProvider>
      </BrowserRouter>
    </QueryClientProvider>
  );
}

That's it. Any plugin registered via registerFrontendPlugin() from @xema-platform/plugin-registry-web automatically:

1. Gets a working HostBridge (its components reach navigation/auth/toast through useHostBridge()).
2. Has its RouteContribution[] rendered in the right place via mountPluginRoutes().
3. Has its NavItemContribution[] mergeable into your sidebar via mergeNavSections(coreSections).

Why an adapter package?

                    plugin source code
                    (uses bridge, no router/auth/toast imports)
                              │
                              ▼
            ┌──────────────────────────────────┐
            │ @xema-dev/plugin-registry-  │
            │  web — shell-agnostic contract   │
            └──────────────────────────────────┘
                              │
        ┌─────────────────────┼─────────────────────────┐
        ▼                     ▼                         ▼
 ┌──────────────┐  ┌──────────────────────┐  ┌─────────────────┐
 │ this package │  │ plugin-host-nextjs   │  │ custom adapter  │
 │ (react-      │  │ (planned)            │  │ (write your own │
 │  router)     │  │                      │  │  bridge)        │
 └──────────────┘  └──────────────────────┘  └─────────────────┘
        │                     │                         │
        ▼                     ▼                         ▼
   Vite SPA           Next.js host              Embedded shell

A new shell type costs one new adapter package, not a fork of every plugin.

API

<DefaultHostBridgeProvider>

Mount inside <BrowserRouter>. Provides a HostBridge to every descendant.

| Prop | Type | Notes | | --- | --- | --- | | auth | AuthSource | Four getters wired to your auth client. | | toast | ToastSource | Three callbacks wired to your toast library. | | queryClient | QueryClient | Your react-query client. | | getCorrelationId? | () => string | Defaults to crypto.randomUUID(). |

mountPluginRoutes({ projectScoped })

Returns a <Fragment> of <Route> elements for plugin route contributions. Filter by projectScoped: true | false so project-scoped routes mount under your /projects/:projectId/* outlet and org-level routes mount at the root.

mergeNavSections(coreSections) and mergeFeatureRouteMap(coreRoutes)

Helpers that merge plugin nav contributions into your sidebar's section structure. Sort is deterministic (weight then key).

Documentation

Full plugin authoring guide and host-adapter contract at docs.xema.dev/plugins.

Related

• @xema-platform/plugin-registry-web — the contract this package implements.
• @xema-platform/plugin-host-sdk — kernel Registry<K, V> primitive.
• @xema-dev/plugin-host-nextjs — Next.js sibling adapter (planned).

License

Apache-2.0.