172 lines
13 KiB
Plaintext
172 lines
13 KiB
Plaintext
page wrnexusssr {
|
|
seo {
|
|
title = "@wrnexus/ssr"
|
|
description = "Secure HTML document rendering and SEO metadata."
|
|
}
|
|
|
|
view {
|
|
<div class="docs-shell">
|
|
<header class="topbar">
|
|
<a class="brand" href="/"><span>W</span> WRNexusJS</a>
|
|
<nav><a href="/getting-started">Get started</a><a href="/packages">Packages</a><a href="/language">Language</a><a href="/architecture">Architecture</a></nav>
|
|
<button data-wire-theme-toggle class="theme-button" aria-label="Toggle theme">Theme</button>
|
|
</header>
|
|
<main class="page package-page">
|
|
<aside class="sidebar"><a href="/packages">← All packages</a><span class="category">Runtime</span><h1>@wrnexus/ssr</h1><p>Secure HTML document rendering and SEO metadata.</p><code>bun add @wrnexus/ssr@0.2.12</code><nav><a href="#guide">Guide</a><a href="#api">Complete API</a></nav></aside>
|
|
<article class="documentation"><section class="doc-intro"><span class="eyebrow">Runtime</span><h1>@wrnexus/ssr</h1><p>Secure HTML document rendering and SEO metadata.</p><pre><code>bun add @wrnexus/ssr@0.2.12</code></pre></section><section id="guide" class="prose"><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>
|
|
<h3 id="installation">Installation</h3>
|
|
<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>
|
|
<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>
|
|
<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="prose api"><h2>Complete TypeScript API</h2><p>This declaration is generated from the exact published package and lists its exported functions, classes, interfaces, and types.</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 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?: string[];
|
|
/** 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;
|
|
}
|
|
/**
|
|
* 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;
|
|
|
|
export { type RenderOptions, renderDocument };
|
|
</code></pre></section><section id="examples" class="prose examples"><h2>Examples</h2><p>Copy-ready examples taken from this package's published documentation.</p><div class="example-grid"><article class="example-card"><h3>Example 1</h3><pre data-language="bash"><code>bun add @wrnexus/ssr</code></pre></article><article class="example-card"><h3>Example 2</h3><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></article><article class="example-card"><h3>Example 3</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></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="#installation">Installation</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-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.12 · SSR-first · Bun-native · Documentation generated from published package APIs.</footer>
|
|
</div>
|
|
}
|
|
}
|