79 lines
2.0 KiB
Markdown
79 lines
2.0 KiB
Markdown
# 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 } }));
|
|
```
|