206 lines
17 KiB
Plaintext
206 lines
17 KiB
Plaintext
page wrnexusssr {
|
|
seo {
|
|
title = "@wrnexus/ssr"
|
|
description = "Secure HTML document rendering and SEO metadata."
|
|
}
|
|
|
|
view {
|
|
<div class="docs-shell">
|
|
<SkipLink label="Skip to content" href="#main" class="docs-skip-link" />
|
|
<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.5.10</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/ssr</span></nav><section class="doc-intro"><span class="eyebrow">Runtime · Package reference</span><h1>@wrnexus/ssr</h1><p>Secure HTML document rendering and SEO metadata.</p><div class="doc-meta"><span>v0.5.10</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/ssr@0.5.10</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>Server-side rendering: wraps a page's HTML body in a complete HTML document with a metadata-driven <code><head></code>.</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>Pages in WRNexusJS return an HTML string for the body. <code>@wrnexus/ssr</code> takes that body and produces a full HTML document — building the <code><head></code> from page metadata and global SEO defaults, resolving canonical/Open Graph/Twitter tags, and injecting module preloads and <code><script type="module"></code> tags. It is deliberately server-only: nothing in this package touches the DOM or ships to the browser, keeping server code genuinely server-only. Reach for it on the server when turning a rendered page body into a response document.</p>
|
|
<pre data-language="bash"><code>bun add @wrnexus/ssr</code></pre>
|
|
<blockquote>Private package — the machine must be authenticated to the <code>wrnexus</code> npm org</blockquote>
|
|
<blockquote>(a read token in <code>~/.npmrc</code>). Requires <strong>Bun</strong> (Node is not supported).</blockquote>
|
|
<h3 id="api">API</h3>
|
|
<p>The package has a single export.</p>
|
|
<h4 id="renderdocument-opts-renderoptions-string"><code>renderDocument(opts: RenderOptions): string</code></h4>
|
|
<p>Renders a complete HTML document as a string, beginning with <code><!doctype html></code>. All metadata is HTML-escaped (via <code>escapeHtml</code> from <code>@wrnexus/core</code>), so a malicious title or description cannot break out of its element or attribute. The body is placed inside <code><div id="app"></code>.</p>
|
|
<h4 id="renderoptions"><code>RenderOptions</code></h4>
|
|
<div class="table-wrap"><table>
|
|
<thead><tr><th>Field</th><th>Type</th><th>Description</th></tr></thead>
|
|
<tbody><tr><td><code>meta</code></td><td><code>PageMeta</code></td><td>Page metadata for the document head (required).</td></tr><tr><td><code>body</code></td><td><code>string</code></td><td>Rendered HTML for the body, placed inside <code>#app</code> (required).</td></tr><tr><td><code>seo</code></td><td><code>SeoConfig</code></td><td>Global SEO defaults, typically from <code>wrnexus.config.ts</code>.</td></tr><tr><td><code>url</code></td><td><code>URL</code></td><td>Current request URL, used to resolve canonical/Open Graph URLs.</td></tr><tr><td><code>scripts</code></td><td><code>string[]</code></td><td>URLs of <code><script type="module"></code> tags to load (e.g. per-island chunks or the reactive runtime). Each also gets a <code><link rel="modulepreload"></code>.</td></tr><tr><td><code>defaultTitle</code></td><td><code>string</code></td><td>Default document title used when <code>meta.title</code> is absent.</td></tr><tr><td><code>extraHead</code></td><td><code>string</code></td><td>Raw HTML injected at the end of <code><head></code> (trusted, framework-controlled — not escaped).</td></tr><tr><td><code>extraBody</code></td><td><code>string</code></td><td>Raw HTML injected at the end of <code><body></code> (trusted, framework-controlled — not escaped).</td></tr><tr><td><code>htmlAttrs</code></td><td><code>string</code></td><td>Attributes for the <code><html></code> element, e.g. <code> data-theme="dark"</code> (trusted).</td></tr></tbody></table></div>
|
|
<p><code>PageMeta</code> and <code>SeoConfig</code> come from <code>@wrnexus/core</code>. <code>PageMeta</code> is an alias of <code>SeoConfig</code>, whose fields are all optional:</p>
|
|
<pre data-language="ts"><code>type SeoConfig = {
|
|
title?: string;
|
|
titleTemplate?: string; // e.g. "%s — My Site"; %s is replaced with the page title
|
|
description?: string;
|
|
canonical?: string;
|
|
canonicalBase?: string; // origin used to absolutize canonical/image URLs
|
|
robots?: string;
|
|
keywords?: string | string[];
|
|
image?: string;
|
|
siteName?: string;
|
|
type?: string; // Open Graph type; defaults to "website"
|
|
locale?: string;
|
|
twitterCard?: string; // defaults to "summary"
|
|
twitterSite?: string;
|
|
themeColor?: string;
|
|
};</code></pre>
|
|
<h4 id="metadata-resolution">Metadata resolution</h4>
|
|
<p><code>renderDocument</code> merges page metadata (<code>meta</code>) over global defaults (<code>seo</code>), field by field, so per-page values win. Notable behavior:</p>
|
|
<ul>
|
|
<li><strong>Title</strong>: uses <code>meta.title</code>, else <code>seo.title</code>, else <code>defaultTitle</code>, else <code>"WRNexusJS"</code>. When the page sets its own title and <code>seo.titleTemplate</code> contains <code>%s</code>, the template is applied.</li>
|
|
<li><strong>Canonical / image URLs</strong>: resolved against <code>canonicalBase</code> (or the request <code>url</code>'s origin) into absolute URLs when possible.</li>
|
|
<li><strong>Keywords</strong>: an array is joined with <code>", "</code>.</li>
|
|
<li><strong>Emitted tags</strong>: <code><title></code>, and as applicable <code>description</code>, <code>robots</code>, <code>keywords</code>, <code>theme-color</code>, and <code>canonical</code> link, plus Open Graph (<code>og:title</code>, <code>og:description</code>, <code>og:type</code>, <code>og:url</code>, <code>og:site_name</code>, <code>og:locale</code>, <code>og:image</code>) and Twitter (<code>twitter:card</code>, <code>twitter:title</code>, <code>twitter:description</code>, <code>twitter:image</code>, <code>twitter:site</code>) meta tags. The document always includes <code>charset</code>, <code>viewport</code>, and a <code>/favicon.ico</code> icon link.</li>
|
|
</ul>
|
|
<h3 id="usage">Usage</h3>
|
|
<h4 id="render-an-seo-ready-application-page">Render an SEO-ready application page</h4>
|
|
<pre data-language="ts"><code>import { renderDocument } from "@wrnexus/ssr";
|
|
|
|
const html = renderDocument({
|
|
meta: {
|
|
title: "About Us",
|
|
description: "Learn more about our team.",
|
|
},
|
|
seo: {
|
|
titleTemplate: "%s — Acme",
|
|
siteName: "Acme",
|
|
canonicalBase: "https://acme.example",
|
|
twitterSite: "@acme",
|
|
},
|
|
url: new URL("https://acme.example/about"),
|
|
body: "<h1>About Us</h1>",
|
|
scripts: ["/_wire/runtime.js", "/_wire/islands/about.js"],
|
|
htmlAttrs: ' data-theme="dark"',
|
|
});
|
|
|
|
return new Response(html, {
|
|
headers: { "content-type": "text/html; charset=utf-8" },
|
|
});</code></pre>
|
|
<p>The produced document has <code><title>About Us — Acme</title></code>, the SEO/Open Graph/Twitter tags derived from the merged metadata, a <code>modulepreload</code> link and module <code><script></code> for each entry in <code>scripts</code>, and the body wrapped in <code><div id="app"></code>.</p>
|
|
<h4 id="add-trusted-framework-assets-and-boot-data">Add trusted framework assets and boot data</h4>
|
|
<p>Use <code>extraHead</code> and <code>extraBody</code> only for HTML generated by your application or the framework. User-provided values belong in <code>meta</code>, where they are escaped.</p>
|
|
<pre data-language="ts"><code>const html = renderDocument({
|
|
meta: { title: "Dashboard", robots: "noindex" },
|
|
body: dashboardHtml,
|
|
url: ctx.url,
|
|
extraHead: '<link rel="stylesheet" href="/_wrnexus/admin.css">',
|
|
extraBody: `<script type="application/json" id="boot">${JSON.stringify(bootData).replaceAll("<", "\\u003c")}</script>`,
|
|
});
|
|
|
|
return new Response(html, { headers: { "content-type": "text/html; charset=utf-8" } });</code></pre>
|
|
<h3 id="requirements-notes">Requirements / Notes</h3>
|
|
<ul>
|
|
<li><strong>Server-only.</strong> This module never imports or touches the DOM and is safe to keep out of client bundles.</li>
|
|
<li><strong>Depends on [<code>@wrnexus/core</code>](../core)</strong> for <code>escapeHtml</code> and the <code>PageMeta</code> / <code>SeoConfig</code> types.</li>
|
|
<li><strong>Bun-only</strong> — like the rest of WRNexusJS, this package targets the Bun runtime (Node is not supported).</li>
|
|
</ul></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 { PageMeta, SeoConfig } from '@wrnexus/core';
|
|
|
|
/**
|
|
* @wrnexus/ssr — server-side rendering.
|
|
*
|
|
* Pages return an HTML string for the body; this module wraps that body in a
|
|
* full document with a `<head>` built from page metadata. It is intentionally
|
|
* isolated from any client runtime: nothing here touches the DOM or ships to
|
|
* the browser, which keeps "server-only code" genuinely server-only.
|
|
*/
|
|
|
|
interface ScriptAsset {
|
|
src: string;
|
|
/** Module scripts are the default for backward compatibility. */
|
|
type?: "module" | "classic";
|
|
async?: boolean;
|
|
defer?: boolean;
|
|
integrity?: string;
|
|
crossOrigin?: "anonymous" | "use-credentials";
|
|
nonce?: string;
|
|
attributes?: Record<string, string | boolean>;
|
|
}
|
|
type RenderScript = string | ScriptAsset;
|
|
interface RenderOptions {
|
|
/** Page metadata for the document head. */
|
|
meta: PageMeta;
|
|
/** Global SEO defaults from `wrnexus.config.ts`. */
|
|
seo?: SeoConfig;
|
|
/** Current request URL, used to resolve canonical/Open Graph URLs. */
|
|
url?: URL;
|
|
/** Rendered HTML for the body (placed inside `#app`). */
|
|
body: string;
|
|
/**
|
|
* URLs of `<script type="module">` tags to load (e.g. per-island chunks or
|
|
* the reactive runtime). Only the scripts a page actually needs are passed.
|
|
*/
|
|
scripts?: RenderScript[];
|
|
/** Optional default document title used when meta.title is absent. */
|
|
defaultTitle?: string;
|
|
/** Raw HTML injected at the end of `<head>` (trusted, framework-controlled). */
|
|
extraHead?: string;
|
|
/** Raw HTML injected at the end of `<body>` (trusted, framework-controlled). */
|
|
extraBody?: string;
|
|
/** Attributes for the `<html>` element, e.g. ` data-theme="dark"` (trusted). */
|
|
htmlAttrs?: string;
|
|
/**
|
|
* Optional application-authored full document shell. It must contain
|
|
* `<html>`, `<head>`, and `<body>`. Framework metadata, assets, and scripts
|
|
* are merged into it instead of wrapping the rendered body again.
|
|
*/
|
|
documentTemplate?: string;
|
|
}
|
|
/**
|
|
* Render a complete HTML document.
|
|
*
|
|
* Metadata is HTML-escaped so a malicious title/description can never break
|
|
* out of its element or attribute.
|
|
*/
|
|
declare function renderDocument(opts: RenderOptions): string;
|
|
interface StreamRenderOptions extends Omit<RenderOptions, "body"> {
|
|
body: string | Promise<string> | AsyncIterable<string>;
|
|
}
|
|
/**
|
|
* Stream a complete document while preserving the exact head/body contract of
|
|
* `renderDocument`. Async iterables can flush a shell, primary content, and
|
|
* slower fragments without buffering the entire route.
|
|
*/
|
|
declare function renderDocumentStream(opts: StreamRenderOptions): ReadableStream<Uint8Array>;
|
|
declare function streamDocumentResponse(opts: StreamRenderOptions, init?: ResponseInit): Response;
|
|
|
|
export { type RenderOptions, type RenderScript, type ScriptAsset, type StreamRenderOptions, renderDocument, renderDocumentStream, streamDocumentResponse };
|
|
</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>Render an SEO-ready application page</h3><pre data-language="ts"><code>import { renderDocument } from "@wrnexus/ssr";
|
|
|
|
const html = renderDocument({
|
|
meta: {
|
|
title: "About Us",
|
|
description: "Learn more about our team.",
|
|
},
|
|
seo: {
|
|
titleTemplate: "%s — Acme",
|
|
siteName: "Acme",
|
|
canonicalBase: "https://acme.example",
|
|
twitterSite: "@acme",
|
|
},
|
|
url: new URL("https://acme.example/about"),
|
|
body: "<h1>About Us</h1>",
|
|
scripts: ["/_wire/runtime.js", "/_wire/islands/about.js"],
|
|
htmlAttrs: ' data-theme="dark"',
|
|
});
|
|
|
|
return new Response(html, {
|
|
headers: { "content-type": "text/html; charset=utf-8" },
|
|
});</code></pre></article><article class="example-card"><h3>Add trusted framework assets and boot data</h3><pre data-language="ts"><code>const html = renderDocument({
|
|
meta: { title: "Dashboard", robots: "noindex" },
|
|
body: dashboardHtml,
|
|
url: ctx.url,
|
|
extraHead: '<link rel="stylesheet" href="/_wrnexus/admin.css">',
|
|
extraBody: `<script type="application/json" id="boot">${JSON.stringify(bootData).replaceAll("<", "\\u003c")}</script>`,
|
|
});
|
|
|
|
return new Response(html, { headers: { "content-type": "text/html; charset=utf-8" } });</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="#renderdocument-opts-renderoptions-string">renderDocument(opts: RenderOptions): string</a><a class="toc-level-4" href="#renderoptions">RenderOptions</a><a class="toc-level-4" href="#metadata-resolution">Metadata resolution</a><a class="toc-level-3" href="#usage">Usage</a><a class="toc-level-4" href="#render-an-seo-ready-application-page">Render an SEO-ready application page</a><a class="toc-level-4" href="#add-trusted-framework-assets-and-boot-data">Add trusted framework assets and boot data</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.5.10</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>
|
|
}
|
|
}
|