docs: update portal for WRNexusJS 0.2.21
This commit is contained in:
@@ -10,12 +10,12 @@ 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="/language">Language</a><a href="/architecture">Architecture</a></nav>
|
||||
<div class="topbar-actions"><a class="preview-pill" href="/access">Private preview · v0.2.20</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.2.21</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="/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="page package-page">
|
||||
<aside class="sidebar"><a href="/packages">← All packages</a><span class="category">Runtime</span><h2>@wrnexus/dev-server</h2><p>Development and production servers, HMR, assets, and gateways.</p><span class="status status-beta">Private preview · 0.2.20</span><nav><a href="#access">Access</a><a href="#guide">Guide</a><a href="#api">Complete API</a></nav></aside>
|
||||
<article id="main" class="documentation"><section class="doc-intro"><span class="eyebrow">Runtime · Preview</span><h1>@wrnexus/dev-server</h1><p>Development and production servers, HMR, assets, and gateways.</p><section id="access" class="access-callout"><h2>Private registry access required</h2><p>This package is not available from the public npm registry. After WorkRoot approves access and supplies private registry instructions, install the release-aligned package:</p><pre><code>bun add @wrnexus/dev-server@0.2.20</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" class="prose"><blockquote>The WRNexusJS HTTP + WebSocket server runtime — request dispatch, SSR document assembly, live-reload (HMR), and the portable production handler.</blockquote>
|
||||
<aside class="sidebar"><a href="/packages">← All packages</a><span class="category">Runtime</span><h2>@wrnexus/dev-server</h2><p>Development and production servers, HMR, assets, and gateways.</p><span class="status status-beta">Private preview · 0.2.21</span><nav><a href="#access">Access</a><a href="#guide">Guide</a><a href="#api">Complete API</a></nav></aside>
|
||||
<article id="main" class="documentation"><section class="doc-intro"><span class="eyebrow">Runtime · Preview</span><h1>@wrnexus/dev-server</h1><p>Development and production servers, HMR, assets, and gateways.</p><section id="access" class="access-callout"><h2>Private registry access required</h2><p>This package is not available from the public npm registry. After WorkRoot approves access and supplies private registry instructions, install the release-aligned package:</p><pre><code>bun add @wrnexus/dev-server@0.2.21</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" class="prose"><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,7 +54,7 @@ interface RunningServer {
|
||||
router: Router;
|
||||
stop(): void;
|
||||
}</code></pre>
|
||||
<p>In development, <code>startServer</code> also connects <code>app/db/migrations</code> (and <code>app/db/<name>/migrations</code>) and auto-applies migrations, then starts an in-process file watcher. CSS edits hot-swap live; any other server change triggers <code>process.exit(RESTART_EXIT_CODE)</code> so the dev supervisor (<code>@wrnexus/cli</code>) respawns the process with fresh modules.</p>
|
||||
<p>In development, <code>startServer</code> also connects <code>app/db/migrations</code> (and <code>app/db/<name>/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>
|
||||
<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 {
|
||||
@@ -118,7 +118,7 @@ interface ProdOptions {
|
||||
}</code></pre>
|
||||
<p><code>createProductionServer</code> also loads the <code>.env</code> cascade for the <code>production</code> profile, installs <code>SIGTERM</code>/<code>SIGINT</code> graceful shutdown, and binds <code>0.0.0.0</code> (port from <code>opts.port</code> or <code>$PORT</code>, default 3000). Migrations are <strong>not</strong> run here — apply them first (<code>wrnexus db migrate</code>). <code>createProductionHandlers</code> returns the bare handlers for edge/serverless/<code>node:http</code> deployment.</p>
|
||||
<h4 id="startgateway-opts-multi-app-gateway"><code>startGateway(opts)</code> — multi-app gateway</h4>
|
||||
<p>Serves several apps behind one port and routes each request to the right app by its <code>Host</code> header. Each app runs as its own child process (full isolation); the gateway is a thin host-based reverse proxy for HTTP and WebSocket. In development, the gateway supervises every child: editing a page, component, API, or middleware restarts only that app and the HMR client reconnects to display the latest page. Apps communicate at runtime via <code>@wrnexus/pubsub</code> (use the Redis driver so messages cross processes).</p>
|
||||
<p>Serves several apps behind one port and routes each request to the right app by its <code>Host</code> header. Each app runs as its own child process (full isolation); the gateway is a thin host-based reverse proxy for HTTP and WebSocket. In development, normal application edits are applied inside the existing child and sent through its existing HMR connection. The child supervisor remains as crash recovery rather than the normal update path. Apps communicate at runtime via <code>@wrnexus/pubsub</code> (use the Redis driver so messages cross processes).</p>
|
||||
<pre data-language="ts"><code>interface GatewayOptions {
|
||||
port?: number; // default 3000
|
||||
hostname?: string; // dev: "127.0.0.1"; production: "0.0.0.0"
|
||||
@@ -246,9 +246,9 @@ declare const RESTART_EXIT_CODE = 97;
|
||||
* { type: "css" } -> the browser hot-swaps the stylesheet (no reload)
|
||||
* { type: "reload" } -> the browser asks for fresh HTML over the HMR socket
|
||||
*
|
||||
* Server-logic changes (pages/api/middleware/realtime) are NOT broadcast here:
|
||||
* they require a fresh process, so the child exits and the supervisor respawns
|
||||
* it. The browser then reconnects and performs a soft DOM morph automatically.
|
||||
* Page/component/API/middleware/realtime changes invalidate their modules and
|
||||
* broadcast `reload` without closing the server or WebSocket. The browser asks
|
||||
* the same process for fresh HTML and performs a soft DOM morph.
|
||||
*/
|
||||
type HmrMessage = {
|
||||
type: "css";
|
||||
@@ -597,8 +597,8 @@ declare function serveNode(handler: FetchHandler, opts?: {
|
||||
* @wrnexus/dev-server — the development HTTP + WebSocket server.
|
||||
*
|
||||
* Thin Bun.serve wrapper around the shared runtime (runtime.ts). Dynamic module
|
||||
* loading makes it fast to iterate; the dev supervisor (see @wrnexus/cli)
|
||||
* restarts this process on file changes.
|
||||
* loading and targeted cache invalidation keep page/component/API edits inside
|
||||
* the running process while the HMR socket morphs fresh HTML into the browser.
|
||||
*/
|
||||
|
||||
interface ServeOptions {
|
||||
@@ -733,7 +733,7 @@ interface ProdOptions {
|
||||
}</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>WRNexusJS 0.2.20 · Private Developer Preview · Bun-native · Documentation generated from installed package APIs.</footer>
|
||||
<footer>WRNexusJS 0.2.21 · Private Developer Preview · Bun-native · Documentation generated from installed package APIs.</footer>
|
||||
</div>
|
||||
}
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user