@canonical/react-ssr 0.21.0 → 0.23.0

package/dist/esm/bin/serve-express.js

@@ -0,0 +1,86 @@
+#!/usr/bin/env node
+/**
+ * Standalone Express server for serving an SSR application.
+ *
+ * Dynamically imports a renderer module that exports a factory function.
+ * The factory receives a Node `IncomingMessage` and returns a renderer.
+ * Supports both streaming and string rendering modes.
+ *
+ * @example
+ * ```sh
+ * # String rendering (default), one static directory
+ * serve-express dist/server/renderer.js --static assets:dist/client/assets
+ *
+ * # Streaming, multiple static directories
+ * serve-express dist/server/renderer.js --streaming \
+ *   --static assets:dist/client/assets \
+ *   --static public:dist/client/public
+ *
+ * # Custom port
+ * serve-express dist/server/renderer.js -p 3000 --static assets:dist/client/assets
+ * ```
+ */
+import path from "node:path";
+import { parseArgs } from "node:util";
+import express from "express";
+import { serveStream } from "#server";
+/**
+ * Parse a `route:filepath` string into its constituent parts.
+ *
+ * @param pair - A string in the format `"route:filepath"`, e.g. `"assets:dist/client/assets"`.
+ * @returns An object with the route prefix and the absolute filesystem path.
+ */
+function parseStaticPair(pair) {
+    const separatorIndex = pair.indexOf(":");
+    if (separatorIndex === -1) {
+        return { route: `/${pair}`, dir: path.join(process.cwd(), pair) };
+    }
+    const route = pair.slice(0, separatorIndex);
+    const filepath = pair.slice(separatorIndex + 1);
+    return {
+        route: `/${route}`,
+        dir: path.join(process.cwd(), filepath),
+    };
+}
+const { values, positionals } = parseArgs({
+    args: process.argv.slice(2),
+    options: {
+        port: {
+            type: "string",
+            alias: "p",
+            default: "5173",
+        },
+        static: {
+            type: "string",
+            alias: "s",
+            multiple: true,
+            default: ["assets:dist/client/assets"],
+        },
+        streaming: {
+            type: "boolean",
+            default: false,
+        },
+    },
+    strict: true,
+    allowPositionals: true,
+});
+const port = Number(values.port) || 5173;
+const rendererFilePath = path.join(process.cwd(), positionals[0]);
+if (!rendererFilePath) {
+    console.error("Usage: serve-express <renderer-path> [--static route:path ...] [--streaming] [-p port]");
+    process.exit(1);
+}
+const createRenderer = await import(rendererFilePath).then((m) => m.default);
+if (typeof createRenderer !== "function") {
+    throw new Error("Renderer module must default-export a factory function (req) => Renderer.");
+}
+const app = express();
+for (const pair of values.static ?? []) {
+    const { route, dir } = parseStaticPair(pair);
+    app.use(route, express.static(dir));
+}
+app.use(serveStream(createRenderer));
+app.listen(port, () => {
+    console.log(`Server started on http://localhost:${port}/`);
+});
+//# sourceMappingURL=serve-express.js.map

package/dist/esm/bin/serve-express.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"serve-express.js","sourceRoot":"","sources":["../../../src/bin/serve-express.ts"],"names":[],"mappings":"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"}

package/dist/esm/index.js

@@ -1,3 +1,3 @@
-export * as renderer from "./renderer/index.js";
-export * as server from "./server/index.js";
+export * as renderer from "./lib/renderer/index.js";
+export * as server from "./lib/server/index.js";
 //# sourceMappingURL=index.js.map

package/dist/esm/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,QAAQ,MAAM,qBAAqB,CAAC;AAChD,OAAO,KAAK,MAAM,MAAM,mBAAmB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,QAAQ,MAAM,yBAAyB,CAAC;AACpD,OAAO,KAAK,MAAM,MAAM,uBAAuB,CAAC"}

package/dist/esm/lib/index.js

@@ -0,0 +1,3 @@
+export * as renderer from "./renderer/index.js";
+export * as server from "./server/index.js";
+//# sourceMappingURL=index.js.map

package/dist/esm/lib/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/lib/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,QAAQ,MAAM,qBAAqB,CAAC;AAChD,OAAO,KAAK,MAAM,MAAM,mBAAmB,CAAC"}

package/dist/esm/lib/renderer/Extractor.js

@@ -0,0 +1,172 @@
+import { toCamelCase } from "@canonical/utils";
+import { Parser } from "htmlparser2";
+import React from "react";
+/**
+ * Maps HTML attribute names to their React prop equivalents.
+ *
+ * React uses camelCase for most DOM attributes, but a handful of common
+ * HTML attributes have specific React names that do not follow the general
+ * camelCase rule. This dictionary covers those exceptions. Any attribute
+ * not listed here falls through to the generic `toCamelCase` converter.
+ */
+const REACT_KEYS_DICTIONARY = {
+    class: "className",
+    for: "htmlFor",
+    crossorigin: "crossOrigin",
+    charset: "charSet",
+};
+/** Tag names that `getOtherHeadElements` collects. */
+const HEAD_OTHER_TAGS = new Set(["title", "style", "meta", "base"]);
+/**
+ * Parse an HTML string and extract all `<head>` elements of interest.
+ *
+ * Uses htmlparser2's SAX `Parser` to stream through the HTML in a single
+ * pass. Each opening tag that matches a head element type is recorded,
+ * and any immediate text content is captured for tags like `<title>` and
+ * `<style>` that carry inline text.
+ *
+ * Elements are returned in document order, grouped into three categories:
+ * links, scripts, and everything else (title, style, meta, base).
+ *
+ * @param html - The full HTML string to parse (typically from a Vite build).
+ * @returns Three arrays of collected elements, in document order.
+ */
+function parseHeadElements(html) {
+    const links = [];
+    const scripts = [];
+    const others = [];
+    let current;
+    const parser = new Parser({
+        onopentag(name, attribs) {
+            if (name === "link" || name === "script" || HEAD_OTHER_TAGS.has(name)) {
+                current = { name, attribs, text: undefined };
+            }
+            else {
+                current = undefined;
+            }
+        },
+        ontext(data) {
+            if (current) {
+                current.text = current.text == null ? data : current.text + data;
+            }
+        },
+        onclosetag(name) {
+            if (!current || current.name !== name)
+                return;
+            // <link> is void — it never has text children
+            if (name === "link") {
+                current.text = undefined;
+            }
+            if (current.name === "link") {
+                links.push(current);
+            }
+            else if (current.name === "script") {
+                scripts.push(current);
+            }
+            else {
+                others.push(current);
+            }
+            current = undefined;
+        },
+    });
+    parser.write(html);
+    parser.end();
+    // Flush any pending <link> that never received an onclosetag.
+    // htmlparser2 fires onclosetag for void elements, so this is a defensive
+    // guard for edge cases in non-standard HTML or alternative parsers.
+    /* v8 ignore next 4 -- defensive: htmlparser2 always fires onclosetag for void elements */
+    if (current?.name === "link") {
+        current.text = undefined;
+        links.push(current);
+    }
+    return { links, scripts, others };
+}
+/**
+ * Extracts `<head>` elements from an HTML string and converts them to React elements.
+ *
+ * The primary use case is server-side rendering with Vite: the build process produces
+ * an HTML shell containing `<script>`, `<link>`, `<meta>`, `<title>`, `<style>`, and
+ * `<base>` tags. This class parses that shell via `parseHeadElements` (a SAX handler —
+ * no DOM tree is constructed) and exposes the extracted tags as React elements that the
+ * server entrypoint component can inject into its rendered output.
+ *
+ * Parsing happens once in the constructor. The three getter methods return the
+ * elements in the order they appeared in the original HTML.
+ */
+export default class Extractor {
+    /** Parsed head elements, grouped by category. */
+    parsed;
+    /**
+     * Create an Extractor for the given HTML string.
+     *
+     * @param html - The full HTML string to parse (typically from a Vite build).
+     */
+    constructor(html) {
+        this.parsed = parseHeadElements(html);
+    }
+    /**
+     * Convert an HTML attribute name to the corresponding React prop name.
+     *
+     * Checks `REACT_KEYS_DICTIONARY` for known exceptions (e.g. `class` becomes
+     * `className`). Falls back to generic camelCase conversion, which correctly
+     * handles `data-*` and `aria-*` attributes.
+     *
+     * @param key - The HTML attribute name, e.g. `"crossorigin"` or `"data-test-id"`.
+     * @returns The React prop name, e.g. `"crossOrigin"` or `"dataTestId"`.
+     */
+    convertKeyToReactKey(key) {
+        return REACT_KEYS_DICTIONARY[key.toLowerCase()] ?? toCamelCase(key);
+    }
+    /**
+     * Convert a collected element into a `React.createElement` call.
+     *
+     * Attributes are mapped to React prop names via `convertKeyToReactKey`.
+     * A stable `key` prop is synthesised from the tag name and the element's
+     * position index so that React can reconcile lists of head elements.
+     *
+     * If the element has text content (e.g. `<title>My App</title>` or
+     * `<style>.body { color: red }</style>`), it is passed as the element's
+     * `children` argument.
+     *
+     * @param element - The collected element data from SAX parsing.
+     * @param index - The position of this element within its sibling group.
+     * @returns A React element matching the original HTML tag.
+     */
+    convertToReactElement(element, index) {
+        const props = {};
+        for (const [key, value] of Object.entries(element.attribs)) {
+            props[this.convertKeyToReactKey(key)] = value;
+        }
+        props.key = `${element.name}_${index}`;
+        return React.createElement(element.name, props, element.text);
+    }
+    /**
+     * Return all `<link>` elements as React elements, in document order.
+     *
+     * Typically used to inject stylesheet and preload links into the
+     * server-rendered `<head>`.
+     */
+    getLinkElements() {
+        return this.parsed.links.map((el, i) => this.convertToReactElement(el, i));
+    }
+    /**
+     * Return all `<script>` elements as React elements, in document order.
+     *
+     * Preserving order is important: Vite dev mode emits module scripts
+     * that depend on being evaluated in sequence.
+     */
+    getScriptElements() {
+        return this.parsed.scripts.map((el, i) => this.convertToReactElement(el, i));
+    }
+    /**
+     * Return all non-script, non-link head elements as React elements, in document order.
+     *
+     * This covers `<title>`, `<style>`, `<meta>`, and `<base>`. Elements are returned
+     * in the order they appeared in the HTML, preserving inter-type ordering (a `<meta>`
+     * between two `<style>` tags stays between them).
+     */
+    getOtherHeadElements() {
+        return this.parsed.others.map((el, i) => this.convertToReactElement(el, i));
+    }
+}
+//# sourceMappingURL=Extractor.js.map

package/dist/esm/lib/renderer/Extractor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Extractor.js","sourceRoot":"","sources":["../../../../src/lib/renderer/Extractor.ts"],"names":[],"mappings":"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"}

package/dist/esm/lib/renderer/JSXRenderer.js

@@ -0,0 +1,283 @@
+import { createElement } from "react";
+import { renderToPipeableStream as reactRenderToPipeableStream, renderToReadableStream as reactRenderToReadableStream, renderToString as reactRenderToString, } from "react-dom/server";
+import { INITIAL_DATA_KEY } from "./constants.js";
+import Extractor from "./Extractor.js";
+/**
+ * Server-side renderer for a React component.
+ *
+ * Accepts a React `ServerEntrypoint` component, optional initial data for
+ * hydration, and an optional HTML shell string (from a Vite build) whose
+ * `<head>` tags are extracted and injected into the rendered output.
+ *
+ * Three rendering strategies are available:
+ *
+ * - **ReadableStream** (`renderToReadableStream`) — returns a web `ReadableStream`.
+ *   Works natively with Bun, Deno, Cloudflare Workers, and any runtime that
+ *   supports the Web Streams API. Supports Suspense and progressive rendering.
+ *
+ * - **PipeableStream** (`renderToPipeableStream`) — returns a Node.js pipeable stream.
+ *   Works with Express, Fastify, and Node's built-in `http` module. Supports Suspense
+ *   and progressive rendering.
+ *
+ * - **String** (`renderToString`) — returns the full HTML as a string. All Suspense
+ *   boundaries resolve synchronously. The output is cacheable and works with Vite
+ *   HMR in dev mode.
+ *
+ * All strategies inject `<script>` and `<link>` tags from the HTML shell via
+ * React's `bootstrapScripts` / `bootstrapModules` mechanism, and embed
+ * `initialData` as a global `window.__INITIAL_DATA__` variable for client
+ * hydration.
+ *
+ * The renderer is transport-agnostic — it never writes to a response object.
+ * HTTP status codes and metadata are exposed via `statusCode` and `statusReady`
+ * for the consumer to use when constructing the response.
+ *
+ * @typeParam TComponent - The server entrypoint component type.
+ * @typeParam InitialData - Shape of the data embedded for client hydration.
+ */
+export default class JSXRenderer {
+    Component;
+    initialData;
+    options;
+    extractor;
+    /**
+     * HTTP status code determined during rendering.
+     *
+     * Starts at 200 and is set to 500 if a shell error occurs during streaming.
+     * For `renderToString`, it is always 200 (errors throw instead).
+     *
+     * Read this after the render method returns (for `renderToReadableStream` and
+     * `renderToString`) or after awaiting `statusReady` (for `renderToPipeableStream`).
+     */
+    statusCode = 200;
+    /**
+     * Resolves when `statusCode` is determined.
+     *
+     * For `renderToReadableStream` and `renderToString`, this is already resolved
+     * by the time the method returns. For `renderToPipeableStream`, it resolves
+     * asynchronously when the shell is ready or errors.
+     */
+    statusReady = Promise.resolve();
+    /**
+     * Create a renderer bound to a specific component and initial data.
+     *
+     * If `options.htmlString` is provided, the HTML is parsed once to extract
+     * `<head>` elements. These elements are then available as React elements
+     * via `getComponentProps()` for injection during rendering.
+     *
+     * @param Component - The React server entrypoint component.
+     * @param initialData - Data to embed in `window.__INITIAL_DATA__` for client hydration.
+     * @param options - Renderer configuration: locale, HTML shell, and stream options.
+     */
+    constructor(Component, initialData = {}, options = {}) {
+        this.Component = Component;
+        this.initialData = initialData;
+        this.options = options;
+        this.extractor = this.options.htmlString
+            ? new Extractor(this.options.htmlString)
+            : undefined;
+    }
+    /**
+     * Return the locale for the rendered page.
+     *
+     * Defaults to `"en"` when no `defaultLocale` was provided in options.
+     * The locale is passed as the `lang` prop to the server entrypoint component,
+     * which typically sets it as the `<html lang>` attribute.
+     */
+    getLocale() {
+        return this.options.defaultLocale || "en";
+    }
+    /**
+     * Assemble the props passed to the server entrypoint component.
+     *
+     * Combines the locale, initial data, and (when an HTML shell was provided)
+     * the extracted script, link, and other head elements into a single props
+     * object conforming to `ServerEntrypointProps`.
+     */
+    getComponentProps() {
+        return {
+            lang: this.getLocale(),
+            scriptElements: this.extractor?.getScriptElements(),
+            linkElements: this.extractor?.getLinkElements(),
+            otherHeadElements: this.extractor?.getOtherHeadElements(),
+            initialData: this.initialData,
+        };
+    }
+    /**
+     * Extract `src` URLs from script elements that match a given loading strategy.
+     *
+     * Filters the provided React `<script>` elements by their `type` attribute:
+     * `"module"` selects ES module scripts, `"classic"` selects everything else.
+     * Returns only the `src` values, discarding inline scripts that have no `src`.
+     *
+     * @param scripts - React elements representing `<script>` tags.
+     * @param type - `"module"` for ES modules, `"classic"` for traditional scripts.
+     * @returns An array of script source URLs.
+     */
+    getScriptSourcesByType(scripts, type) {
+        return scripts
+            .map((script) => script)
+            .filter((script) => {
+            if (type === "module") {
+                return script.props.type === "module";
+            }
+            return script.props.type !== "module";
+        })
+            .map((script) => script.props.src)
+            .filter((src) => typeof src === "string");
+    }
+    /**
+     * Merge renderer-managed options into the user-provided stream options.
+     *
+     * Populates three React streaming options unless the caller already supplied them:
+     *
+     * - `bootstrapScriptContent` — a `<script>` body that assigns `initialData` to
+     *   `window.__INITIAL_DATA__`. The JSON is escaped to prevent `</script>` injection.
+     * - `bootstrapScripts` — `src` URLs for classic (non-module) scripts extracted from
+     *   the HTML shell. React strips `<script>` tags during streaming, so these must
+     *   be re-injected through this mechanism.
+     * - `bootstrapModules` — same as above, for ES module scripts.
+     *
+     * @param props - The assembled component props (used to read `initialData` and `scriptElements`).
+     * @returns A merged options object safe to pass to either streaming API.
+     */
+    enrichRendererOptions(props) {
+        const enrichedOptions = {
+            ...this.options.renderToPipeableStreamOptions,
+        };
+        if (!enrichedOptions.bootstrapScriptContent) {
+            if (props.initialData) {
+                enrichedOptions.bootstrapScriptContent = `window.${INITIAL_DATA_KEY} = ${JSON.stringify(props.initialData).replace(/</g, "\\u003c")}`;
+            }
+        }
+        if (!enrichedOptions.bootstrapScripts) {
+            if (props.scriptElements) {
+                enrichedOptions.bootstrapScripts = this.getScriptSourcesByType(props.scriptElements, "classic");
+            }
+        }
+        if (!enrichedOptions.bootstrapModules) {
+            if (props.scriptElements) {
+                enrichedOptions.bootstrapModules = this.getScriptSourcesByType(props.scriptElements, "module");
+            }
+        }
+        return enrichedOptions;
+    }
+    /**
+     * Render the component to a web `ReadableStream`.
+     *
+     * Uses `react-dom/server.renderToReadableStream` for environments that support
+     * the Web Streams API (Bun, Deno, Cloudflare Workers, browsers). Supports
+     * Suspense and progressive rendering.
+     *
+     * On shell error, `statusCode` is set to 500 and a fallback HTML stream is
+     * returned. On success, `statusCode` is 200.
+     *
+     * @note This method is impure — it mutates `statusCode` and `statusReady`.
+     *
+     * @param signal - Optional `AbortSignal` for request cancellation.
+     * @returns A `ReadableStream` of the rendered HTML.
+     */
+    renderToReadableStream = async (signal) => {
+        const props = this.getComponentProps();
+        const jsx = createElement(this.Component, props);
+        const { onError: onErrorCallback, 
+        // Strip pipeable-only callbacks — they don't exist on RenderToReadableStreamOptions
+        onShellReady: _onShellReady, onShellError: _onShellError, onAllReady: _onAllReady, ...options } = this.enrichRendererOptions(props);
+        try {
+            const stream = await reactRenderToReadableStream(jsx, {
+                ...options,
+                ...(this.options.renderToReadableStreamOptions ?? {}),
+                signal,
+                onError: (error, errorInfo) => {
+                    onErrorCallback?.(error, errorInfo);
+                    console.error(error);
+                },
+            });
+            this.statusCode = 200;
+            this.statusReady = Promise.resolve();
+            return stream;
+        }
+        catch (error) {
+            console.error(error);
+            this.statusCode = 500;
+            this.statusReady = Promise.resolve();
+            return new ReadableStream({
+                start(controller) {
+                    controller.enqueue(new TextEncoder().encode("<h1>Something went wrong</h1>"));
+                    controller.close();
+                },
+            });
+        }
+    };
+    /**
+     * Render the component to a Node.js pipeable stream.
+     *
+     * Uses `react-dom/server.renderToPipeableStream` for Node.js environments
+     * (Express, Fastify, plain `http.createServer`). Supports Suspense and
+     * progressive rendering.
+     *
+     * Returns `{ pipe, abort }` synchronously. The `statusCode` is set
+     * asynchronously when the shell is ready or errors — await `statusReady`
+     * before reading it.
+     *
+     * @note This method is impure — it mutates `statusCode` and `statusReady`.
+     *
+     * @returns The pipe/abort handles for the rendered stream.
+     */
+    renderToPipeableStream = () => {
+        const props = this.getComponentProps();
+        const jsx = createElement(this.Component, props);
+        const { onShellError: onShellErrorCallback, onShellReady: onShellReadyCallback, onAllReady: onAllReadyCallback, onError: onErrorCallback, ...options } = this.enrichRendererOptions(props);
+        const errorRef = { current: undefined };
+        let resolveStatus;
+        this.statusReady = new Promise((resolve) => {
+            resolveStatus = resolve;
+        });
+        const jsxStream = reactRenderToPipeableStream(jsx, {
+            ...options,
+            onError(error, errorInfo) {
+                onErrorCallback?.(error, errorInfo);
+                errorRef.current = error;
+                console.error(error);
+            },
+            onShellError: (error) => {
+                onShellErrorCallback?.(error);
+                this.statusCode = 500;
+                resolveStatus();
+                console.error(error);
+            },
+            onShellReady: () => {
+                onShellReadyCallback?.();
+                /* v8 ignore next -- errorRef.current is set by onError which fires before onShellReady in edge cases */
+                this.statusCode = errorRef.current ? 500 : 200;
+                resolveStatus();
+            },
+            onAllReady() {
+                onAllReadyCallback?.();
+            },
+        });
+        return { pipe: jsxStream.pipe, abort: jsxStream.abort };
+    };
+    /**
+     * Render the component to a complete HTML string.
+     *
+     * Uses `react-dom/server.renderToString` to produce the full HTML
+     * synchronously. All Suspense boundaries resolve before the method returns.
+     * The output is cacheable and compatible with Vite's HMR in dev mode.
+     *
+     * Sets `statusCode` to 200 on success. On error, throws (consumer catches).
+     *
+     * @note This method is impure — it mutates `statusCode`.
+     *
+     * @returns The complete HTML string.
+     */
+    renderToString = () => {
+        const props = this.getComponentProps();
+        const jsx = createElement(this.Component, props);
+        const html = reactRenderToString(jsx);
+        this.statusCode = 200;
+        this.statusReady = Promise.resolve();
+        return html;
+    };
+}
+//# sourceMappingURL=JSXRenderer.js.map

package/dist/esm/lib/renderer/JSXRenderer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"JSXRenderer.js","sourceRoot":"","sources":["../../../../src/lib/renderer/JSXRenderer.ts"],"names":[],"mappings":"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"}