WRNexusJS/packages/dev-toolbar/INTEGRATION.md

WRNexusJS DevServer integration

1. Add workspace dependency

"@wrnexus/dev-toolbar": "workspace:*"

2. Create a collector when development starts

import { createDevToolbarCollector } from "@wrnexus/dev-toolbar/server";

const collector = mode === "development" ? createDevToolbarCollector() : undefined;

3. Handle toolbar routes before public-file fallback

import { handleDevToolbarRoute } from "@wrnexus/dev-toolbar/server";

const toolbarResponse = collector
  ? await handleDevToolbarRoute(request, {
      mode,
      root: appRoot,
      collector,
      editor: config.devToolbar?.editor,
      allowOpenEditor: config.devToolbar?.openEditor !== false,
    })
  : null;

if (toolbarResponse) return toolbarResponse;

4. Inject toolbar in full HTML documents

function injectDevToolbar(html: string): string {
  if (mode !== "development") return html;
  const script =
    '<script type="module" src="/__wrnexus/dev-toolbar.js" data-wrnexus-dev-toolbar></script>';
  return html.includes("</body>")
    ? html.replace("</body>", `${script}</body>`)
    : `${html}${script}`;
}

Do not inject into APIs, JSON, XML, assets, downloads, or navigation fragments. Keep the toolbar outside #app so CSR navigation does not destroy it.

5. Add server errors

import { issueFromError } from "@wrnexus/dev-toolbar/server";

try {
  return await renderPage();
} catch (error) {
  collector?.add(
    issueFromError(error, {
      ruleId: "server/render-error",
      category: "server",
      title: "Page rendering failed",
      pathname: new URL(request.url).pathname,
    }),
  );
  throw error;
}

6. Notify browser after HMR/navigation

Dispatch one of these events from existing runtimes:

window.dispatchEvent(new CustomEvent("wrnexus:hmr"));
window.dispatchEvent(new CustomEvent("wrnexus:navigated", { detail: { pathname } }));
window.dispatchEvent(new CustomEvent("wrnexus:runtime-error", { detail: { message, stack } }));