# WRNexusJS DevServer integration

## 1. Add workspace dependency

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

## 2. Create a collector when development starts

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

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

## 3. Handle toolbar routes before public-file fallback

```ts
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

```ts
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

```ts
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:

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