WorkRoot/WRNexusJSDoc
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: update portal for WRNexusJS 0.8.0

Browse Source
This commit is contained in:
Clintchiz
2026-08-02 23:57:41 +05:30
parent 9366895f78
commit 8d5d4b8f12
183 changed files with 14433 additions and 2492 deletions
Download Patch File Download Diff File Expand all files Collapse all files
app/pages/packages/dev-server.wrn
+65 -8
View File
@@ -10,11 +10,11 @@ page wrnexusdevserver {
<header class="topbar">
<a class="brand" href="/"><span>W</span> WRNexusJS</a>
<nav aria-label="Primary"><a href="/getting-started">Get started</a><a href="/packages">Packages</a><a href="https://component.wrnexusjs.dev/">Components</a><a href="/language">Language</a><a href="/architecture">Architecture</a></nav>
<div class="topbar-actions"><a class="preview-pill" href="/access">Private preview · v0.7.0</a><button data-wire-theme-toggle class="theme-button" aria-label="Toggle color theme" title="Toggle color theme">◐</button></div>
<div class="topbar-actions"><a class="preview-pill" href="/access">Private preview · v0.8.0</a><button data-wire-theme-toggle class="theme-button" aria-label="Toggle color theme" title="Toggle color theme">◐</button></div>
</header>
<div class="mobile-doc-nav"><details><summary>Browse documentation</summary><nav><a href="/getting-started">Get started</a><a href="/packages">Packages</a><a href="https://component.wrnexusjs.dev/">Components</a><a href="/language">Language</a><a href="/architecture">Architecture</a><a href="/tutorial">Tutorial</a><a href="/guides/project-structure">Guides</a><a href="/examples">Examples</a><a href="/search">Search</a></nav></details></div>
<main class="portal-main docs-layout">
<article id="main" class="documentation prose standalone package-document"><nav class="breadcrumbs" aria-label="Breadcrumb"><a href="/">Home</a><span>/</span><a href="/packages">Packages</a><span>/</span><span aria-current="page">@wrnexus/dev-server</span></nav><section class="doc-intro"><span class="eyebrow">Runtime · Package reference</span><h1>@wrnexus/dev-server</h1><p>Development and production servers, HMR, assets, and gateways.</p><div class="doc-meta"><span>v0.7.0</span><span>Private registry</span><span>Runtime</span></div><section id="access" class="access-callout"><h2>Install the package</h2><p>After WorkRoot approves private registry access, install the release-aligned package:</p><pre><code>bun add @wrnexus/dev-server@0.7.0</code><button type="button" class="copy-button" aria-label="Copy installation command">Copy</button></pre><p><a href="/access">Request preview access</a>. Never put registry tokens in source control.</p></section></section><section id="guide"><blockquote>The WRNexusJS HTTP + WebSocket server runtime — request dispatch, SSR document assembly, live-reload (HMR), and the portable production handler.</blockquote>
<article id="main" class="documentation prose standalone package-document"><nav class="breadcrumbs" aria-label="Breadcrumb"><a href="/">Home</a><span>/</span><a href="/packages">Packages</a><span>/</span><span aria-current="page">@wrnexus/dev-server</span></nav><section class="doc-intro"><span class="eyebrow">Runtime · Package reference</span><h1>@wrnexus/dev-server</h1><p>Development and production servers, HMR, assets, and gateways.</p><div class="doc-meta"><span>v0.8.0</span><span>Private registry</span><span>Runtime</span></div><section id="access" class="access-callout"><h2>Install the package</h2><p>After WorkRoot approves private registry access, install the release-aligned package:</p><pre><code>bun add @wrnexus/dev-server@0.8.0</code><button type="button" class="copy-button" aria-label="Copy installation command">Copy</button></pre><p><a href="/access">Request preview access</a>. Never put registry tokens in source control.</p></section></section><section id="guide"><blockquote>The WRNexusJS HTTP + WebSocket server runtime — request dispatch, SSR document assembly, live-reload (HMR), and the portable production handler.</blockquote>
<p>Part of the <strong>WRNexusJS</strong> framework — an SSR-first, Bun-native full-stack web framework.</p>
<h3 id="overview">Overview</h3>
<p>This package is the server runtime that powers a WRNexusJS app in both development and production. A single <strong>request runtime</strong> (<code>createHandlers</code>) owns HTTP/WebSocket dispatch and SSR document assembly; it knows nothing about _how_ modules and assets are produced, so the dev and prod entry points wire in different backends: dev uses dynamic module loading plus on-the-fly bundling and injects a live-reload client; prod uses a static, pre-built manifest with cache-immutable assets. The package also ships a multi-app <strong>gateway</strong> (route several apps by <code>Host</code> header behind one port) and a portable <code>node:http</code> adapter for WinterCG hosts. It is entirely server-side and Bun-native (<code>Bun.serve</code>, <code>Bun.file</code>, <code>Bun.gzipSync</code>).</p>
@@ -54,6 +54,7 @@ interface RunningServer &#123;
stop(): void;
&#125;</code></pre>
<p>In development, <code>startServer</code> also connects <code>app/db/migrations</code> (and <code>app/db/&lt;name&gt;/migrations</code>) and auto-applies migrations, then starts an in-process file watcher. CSS edits hot-swap live. Page, component, layout, API, middleware, realtime, schema, locale, and public-asset edits invalidate only their cached modules, rescan routes where necessary, and morph fresh HTML through the existing HMR WebSocket. The server process and active gateway stay running.</p>
<p><code>getWrnCompileMetrics()</code> exposes cumulative content-addressed compiler cache <code>hits</code>, <code>misses</code>, successful <code>compilations</code>, <code>errors</code>, <code>totalDurationMs</code>, and <code>lastDurationMs</code> for the DevToolbar or custom diagnostics. Tests and embedded servers can call <code>resetWrnCompileMetrics()</code> to establish a fresh measurement window.</p>
<h4 id="createhandlers-deps"><code>createHandlers(deps)</code></h4>
<p>The core runtime shared by dev and prod. It handles CORS preflight, <code>/healthz</code> and <code>/__wrnexus/health</code>, request-body size limits (413), HMR socket upgrades (<code>/__wrnexus/hmr</code>), realtime WebSocket upgrades (<code>defineRoom</code> default export or a raw <code>websocket</code> export), the middleware pipeline, API routes (<code>/api/*</code>), framework assets (<code>/__wrnexus/*</code>), public assets, and full SSR page rendering (component mounts, layouts, slots, i18n markers, per-page script selection, ETag/304, gzip).</p>
<pre data-language="ts"><code>interface RuntimeDeps &#123;
@@ -222,23 +223,63 @@ await startGateway(&#123;
<ul>
<li><strong>Bun-only.</strong> Uses <code>Bun.serve</code> (HTTP + WebSocket), <code>Bun.file</code>, and <code>Bun.gzipSync</code>. The full app also relies on <code>bun:sqlite</code> / <code>Bun.SQL</code> via <code>@wrnexus/db</code>.</li>
<li>Orchestrates the whole framework: <code>@wrnexus/core</code> (context, security, realtime registry), <code>@wrnexus/router</code>, <code>@wrnexus/ssr</code> (<code>renderDocument</code>), <code>@wrnexus/csr</code> (client runtimes), <code>@wrnexus/compiler</code> (<code>.wrn</code> → TS), <code>@wrnexus/styles</code>, <code>@wrnexus/ui</code>, <code>@wrnexus/validation</code>, <code>@wrnexus/i18n</code>, <code>@wrnexus/db</code>, and <code>@wrnexus/pubsub</code> (Redis-backed cross-process realtime).</li>
<li><code>.wrn</code> files are compiled to TypeScript into a hidden sibling <code>.wrnexus/</code> cache dir and dynamically imported; the module cache means each edited server module needs a fresh process (dev) — hence the restart-on-change model.</li>
<li><code>.wrn</code> files compile into a content-addressed hidden <code>.wrnexus/</code> cache. Targeted</li>
<p>invalidation gives changed modules a fresh import identity without restarting the development server.</p>
<li>Responses are gzipped when the client accepts it and the body is a buffered, compressible payload ≥ 1 KB; streaming/SSE responses opt out via <code>Cache-Control: no-transform</code>.</li>
<p>&lt;/content&gt;</p>
</ul>
<p>&lt;/invoke&gt;</p></section><section id="api" class="api"><h2>Complete TypeScript API</h2><p>Generated from the exact installed package declarations.</p><pre data-language="typescript"><code>import &#123; Mode, Middleware, SeoConfig, SecurityConfig, RealtimeBus, RealtimeConnectMeta &#125; from '@wrnexus/core';
<p>&lt;/invoke&gt;</p></section><section id="api" class="api"><h2>Complete TypeScript API</h2><p>Generated from the exact installed package declarations.</p><pre data-language="typescript"><code>import &#123; Mode, Middleware, SeoConfig, SecurityConfig, HealthRegistry, RealtimeBus, RealtimeConnectMeta &#125; from '@wrnexus/core';
import &#123; Router &#125; from '@wrnexus/router';
import &#123; ResolvedTheme, MobileConfig, PwaConfig, ObservabilityConfig, TenancyConfig, NavigationConfig, StylesConfig, ThemeConfig &#125; from '@wrnexus/styles';
import &#123; ResolvedI18n, I18nConfig &#125; from '@wrnexus/i18n';
import &#123; StorageConfig &#125; from '@wrnexus/uploader';
import &#123; DevToolbarConfig, DevToolbarPlatformSnapshot, DevToolbarPanel &#125; from '@wrnexus/dev-toolbar/types';
import &#123; ClientRuntimeDefinition, PluginInput &#125; from '@wrnexus/plugin';
import &#123; CacheCoordinator &#125; from '@wrnexus/cache';
import &#123; DevToolbarCollector &#125; from '@wrnexus/dev-toolbar/server';
import &#123; IncomingMessage, ServerResponse, Server &#125; from 'node:http';
/** Exit code a dev-server child uses to request a clean supervisor restart. */
declare const RESTART_EXIT_CODE = 97;
interface PartialBuildModule &#123;
default?: unknown;
render?: (props?: Record&lt;string, unknown&gt;) =&gt; string | Promise&lt;string&gt;;
layout?: string | &#123;
name?: string;
render?: (props?: Record&lt;string, unknown&gt;) =&gt; string;
&#125;;
__wrnexusBuildStaticShell?: (ctx?: Record&lt;string, unknown&gt;) =&gt; string | Promise&lt;string&gt;;
&#125;
interface PartialBuildEntry &#123;
name: string;
mod: PartialBuildModule;
&#125;
/** Expand compiler component mounts at build time using only their pure render exports. */
declare function expandStaticComponents(html: string, components: readonly PartialBuildEntry[], depth?: number): Promise&lt;string&gt;;
/** Produce the body shell stored in dist; dynamic region bodies are never evaluated here. */
declare function precomputePartialStaticShell(page: PartialBuildModule, components: readonly PartialBuildEntry[]): Promise&lt;&#123;
shell: string;
regions: number;
&#125;&gt;;
/**
* Request pipeline helpers: middleware execution and safe module loading.
* These are deliberately runtime-agnostic (no Bun APIs) so they could run on
* Node too.
*/
interface WrnCompileMetrics &#123;
hits: number;
misses: number;
compilations: number;
errors: number;
totalDurationMs: number;
lastDurationMs: number;
&#125;
declare function getWrnCompileMetrics(): Readonly&lt;WrnCompileMetrics&gt;;
declare function resetWrnCompileMetrics(): void;
/**
* HMR hub — tracks connected browser HMR sockets and broadcasts update events.
*
@@ -349,6 +390,8 @@ interface RuntimeDeps &#123;
security?: SecurityConfig;
/** Built-in request tracing and Server-Timing policy. */
observability?: ObservabilityConfig;
/** Dependency health checks used by `/readyz` and `/__wrnexus/ready`. */
health?: HealthRegistry;
/** Built-in tenant identity resolution. */
tenancy?: TenancyConfig;
/** Max request body size in bytes (413 above this). Default 10 MB. */
@@ -361,12 +404,16 @@ interface RuntimeDeps &#123;
* bus (use the Redis pub/sub driver). Enables realtime across multiple apps.
*/
realtimeBus?: RealtimeBus;
/** Shared first-class data/component/page caches. */
cache?: CacheCoordinator;
/** Final document transform supplied by the plugin render lifecycle. */
renderHtml?: (html: string) =&gt; string | Promise&lt;string&gt;;
devToolbar?: &#123;
config: DevToolbarConfig;
collector: DevToolbarCollector;
root: string;
platform?: DevToolbarPlatformSnapshot;
panels?: DevToolbarPanel[];
panels?: DevToolbarPanel[] | (() =&gt; DevToolbarPanel[] | Promise&lt;DevToolbarPanel[]&gt;);
&#125;;
&#125;
interface UpgradeServer &#123;
@@ -500,7 +547,8 @@ declare function startGateway(opts: GatewayOptions): Promise&lt;RunningGateway&g
* `wrnexus build` generates an entry that statically imports every route and
* component module and hands them here as a manifest. We rebuild the (cheap)
* route-matching tables from the raw patterns and run the exact same request
* runtime as dev — just with production error pages and no live-reload client.
* runtime as dev. Normal preview/deploy output has no live-reload client; the
* supervised `dev --production-runtime` mode can explicitly enable it.
*/
type RouteModule = Record&lt;string, unknown&gt;;
@@ -509,6 +557,8 @@ interface ManifestRoute &#123;
raw: string;
/** The statically-imported route module. */
mod: RouteModule;
/** Body shell precomputed by `wrnexus build` for a partial-static page. */
staticShell?: string;
&#125;
interface ProdManifest &#123;
pages: ManifestRoute[];
@@ -609,6 +659,8 @@ interface ProdOptions &#123;
port?: number;
hostname?: string;
maxBodyBytes?: number;
/** Enable only for the CLI's supervised exact-production development mode. */
developmentRuntime?: boolean;
&#125;
/**
* Build the portable request handler from a precompiled manifest — a
@@ -663,6 +715,11 @@ interface ServeOptions &#123;
appDir: string;
port?: number;
hostname?: string;
/** Development TLS material. Production TLS is normally terminated by the deployment proxy. */
tls?: &#123;
cert: string;
key: string;
&#125;;
mode?: Mode;
/** Inject the live-reload client (defaults to true in development). */
hmr?: boolean;
@@ -715,7 +772,7 @@ interface RunningServer &#123;
&#125;
declare function startServer(opts: ServeOptions): Promise&lt;RunningServer&gt;;
export &#123; type AssetServer, type FetchHandler, type GatewayApp, type GatewayAuth, type GatewayOptions, type GatewaySecurity, RESTART_EXIT_CODE, type RunningGateway, type RunningServer, type RuntimeDeps, type ServeOptions, type WsData, createHandlers, createProductionHandlers, createProductionServer, nodeListener, serveNode, startGateway, startServer, toRequest, writeResponse &#125;;
export &#123; type AssetServer, type FetchHandler, type GatewayApp, type GatewayAuth, type GatewayOptions, type GatewaySecurity, RESTART_EXIT_CODE, type RunningGateway, type RunningServer, type RuntimeDeps, type ServeOptions, type WrnCompileMetrics, type WsData, createHandlers, createProductionHandlers, createProductionServer, expandStaticComponents, getWrnCompileMetrics, nodeListener, precomputePartialStaticShell, resetWrnCompileMetrics, serveNode, startGateway, startServer, toRequest, writeResponse &#125;;
</code></pre></section><section id="examples" class="examples"><h2>Examples</h2><p>Copy-ready examples from the installed package documentation.</p><div class="example-grid"><article class="example-card"><h3>Programmatic dev server</h3><pre data-language="ts"><code>import &#123; startServer &#125; from &quot;@wrnexus/dev-server&quot;;
const server = await startServer(&#123;
@@ -756,7 +813,7 @@ await startGateway(&#123;
&#125;);</code></pre></article></div></section></article>
<aside class="on-this-page"><h2>On this page</h2><nav><a class="toc-level-2" href="#guide">Guide</a><a class="toc-level-3" href="#overview">Overview</a><a class="toc-level-3" href="#api">API</a><a class="toc-level-4" href="#main-entry-wrnexus-dev-server">Main entry (@wrnexus/dev-server)</a><a class="toc-level-4" href="#startserver-opts">startServer(opts)</a><a class="toc-level-4" href="#createhandlers-deps">createHandlers(deps)</a><a class="toc-level-4" href="#createproductionserver-manifest-opts-createproductionhandlers-manifest-opts">createProductionServer(manifest, opts) / createProductionHandlers(manifest, opts)</a><a class="toc-level-4" href="#startgateway-opts-multi-app-gateway">startGateway(opts) — multi-app gateway</a><a class="toc-level-4" href="#node-http-adapter-from-adapters-node-ts">node:http adapter (from ./adapters/node.ts)</a><a class="toc-level-4" href="#subpath-export-wrnexus-dev-server-serve-entry">Subpath export: @wrnexus/dev-server/serve-entry</a><a class="toc-level-3" href="#usage">Usage</a><a class="toc-level-4" href="#programmatic-dev-server">Programmatic dev server</a><a class="toc-level-4" href="#production-server-from-a-build-manifest">Production server from a build manifest</a><a class="toc-level-4" href="#embedding-the-handler-on-node-http">Embedding the handler on node:http</a><a class="toc-level-4" href="#multi-app-gateway">Multi-app gateway</a><a class="toc-level-3" href="#framework-asset-routes">Framework asset routes</a><a class="toc-level-3" href="#requirements-notes">Requirements / Notes</a><a class="toc-level-2" href="#api">Complete API</a><a class="toc-level-2" href="#examples">Examples</a></nav></aside>
</main>
<footer><div class="footer-brand"><span class="footer-mark" aria-hidden="true">W</span><p><strong>WRNexusJS 0.7.0</strong><span>Complete API documentation generated from installed package declarations.</span></p></div><nav aria-label="Footer"><a href="/packages">All packages</a><a href="/getting-started">Get started</a><a href="/security">Security</a><a href="/support">Support</a><a href="/llms.txt">AI guide</a></nav><p class="footer-meta">Private Developer Preview · Bun-native</p></footer>
<footer><div class="footer-brand"><span class="footer-mark" aria-hidden="true">W</span><p><strong>WRNexusJS 0.8.0</strong><span>Complete API documentation generated from installed package declarations.</span></p></div><nav aria-label="Footer"><a href="/packages">All packages</a><a href="/getting-started">Get started</a><a href="/security">Security</a><a href="/support">Support</a><a href="/llms.txt">AI guide</a></nav><p class="footer-meta">Private Developer Preview · Bun-native</p></footer>
<BackToTop />
</div>
}