Skip to content

API

@ogygia/rewrite

Render custom elements, or rewrite the whole page, on the HTML ogygia sends; ogygia puts back what the render moved before anything hydrates.

On this page

This page is generated from the package’s own .d.ts files on every build, so the signatures, descriptions and examples below always match the source.

import { … } from '@ogygia/rewrite';

Exports rewrite · CheckOptions · ElementRewrite · PageRewrite · RewriteCheck · RewriteContext · RewriteElement · RewriteSheet · Rewrite · RewriteKind · RewriteResult · WholePageRewrite

rewrite

function

A rewrite of the HTML ogygia sends, as a Kit handle. List it before ogygia.handle(), and rewrite() (from @ogygia/rewrite/vite) beside ogygia() in vite.config:

// src/hooks.server.ts
import { sequence } from '@sveltejs/kit/hooks';
import * as ogygia from 'ogygia/server';
import { rewrite } from '@ogygia/rewrite';

const components = rewrite({
	match: 'x-',
	async render(elements, ctx) {
		return elements.map((el) => ({ html: renderElement(el.html), sheets: [] }));
	}
});
export const handle = sequence(components, ogygia.handle());
  • { match, render }: the outermost elements match picks go to render, one call per chunk of the page (and per region answer), which returns one { html, sheets } per element. A failed batch is retried one element at a time; an element that still fails goes out as ogygia rendered it, said with its code. Each sheet goes out once per key: into the head, or inline at its first use once the head has gone.
  • { page }: the whole document or region answer. The document is held until its last chunk. The value also has .html(str), the page function on a plain string.

An element render gets with restored: true is one ogygia puts back for Svelte: render its plan (its children inside <slot> wrappers, og-shadow="key …" naming its shadow sheets, optionally og-keep="attr …"), and carry every other og-* mark along wherever you move a node.

Several rewrites run in the order they are listed, on one marking of the HTML: a later one sees an earlier one's output. .check(html, { kind, csr }) runs the whole round trip on one piece of markup, for a test.

function rewrite(definition: ElementRewrite): Rewrite;
function rewrite(definition: PageRewrite): WholePageRewrite;

CheckOptions

interface

The response .check() stands in for.

interface CheckOptions {/*…*/}

CheckOptions.kind

Default 'region'.

kind?: RewriteKind;

CheckOptions.csr

Default false.

csr?: boolean;

CheckOptions.event

Default: a GET for /.

event?: RequestEvent;

ElementRewrite

interface

A rewrite of the elements match picks.

interface ElementRewrite {/*…*/}

ElementRewrite.match

Which elements go to render: every custom element whose name starts with this prefix, exactly these names, or the names this test accepts. Only the outermost match is sent; a match inside it goes with it.

match: MatchSpec;

ElementRewrite.render

Renders a batch: one result per element, in order. Called once per chunk of the page with that chunk's elements, and once per region answer.

render(elements: readonly RewriteElement[], ctx: RewriteContext): Promise<readonly RewriteResult[]> | readonly RewriteResult[];

PageRewrite

interface

A rewrite of the whole document or region answer.

interface PageRewrite {/*…*/}

PageRewrite.page

The whole document, or the whole region answer. A document it runs on is held until its last chunk and rewritten once.

page(html: string, ctx: RewriteContext): Promise<string> | string;

RewriteCheck

interface

What .check() found.

interface RewriteCheck {/*…*/}

RewriteCheck.html

The HTML as ogygia would send it (marked, rewritten, settled, the restorer in place).

html: string;

RewriteCheck.head

What went into <head> (a document), or what an answer carries for the head.

head: readonly string[];

RewriteCheck.restored

How many hosts ogygia restores.

restored: number;

RewriteCheck.failed

Each element whose render failed, with the reason; each one went out as ogygia rendered it.

failed: readonly {
    name: string;
    error: string;
  }[];

RewriteCheck.dom

The parsed and restored DOM, when there is a DOM (vitest browser mode, jsdom); else null.

dom: Document | DocumentFragment | null;

RewriteCheck.mismatches

Each restored host whose light DOM is not exactly what Svelte rendered.

mismatches: readonly string[];

RewriteContext

interface

What ogygia knows about the HTML being rewritten.

interface RewriteContext {/*…*/}

RewriteContext.kind

'document': a page render. 'region': a region answer (a hole, a lake remount).

kind: RewriteKind;

RewriteContext.csr

Kit hydrates the whole page. Always false for a region answer.

csr: boolean;

RewriteContext.url

The URL of the request being answered.

url: URL;

RewriteContext.event

The request being answered.

event: RequestEvent;

RewriteContext.signal

Fires when the request is cancelled (the visitor left): stop the render, nothing reads it.

signal: AbortSignal;

RewriteElement

interface

One outermost element match picked, as render gets it.

interface RewriteElement {/*…*/}

RewriteElement.name

The tag name, lower-case.

readonly name: string;

RewriteElement.html

Its outer HTML. ogygia's marks inside are numbered from 0, so the same element has the same bytes on every page: a cache can key on html.

readonly html: string;

RewriteElement.restored

ogygia puts this element back for Svelte before anything hydrates (it carries og-h): render its plan (its children inside <slot> wrappers, og-shadow, optionally og-keep). When false, render it any way you like.

readonly restored: boolean;

RewriteSheet

interface

A sheet a render needs, sent once per key per response.

interface RewriteSheet {/*…*/}

RewriteSheet.key

key: string;

RewriteSheet.css

css: string;

RewriteSheet.scope

'page': a <style> for the document. 'shadow': a sheet a restored host names in og-shadow.

scope: "page" | "shadow";

Rewrite

type

A rewrite: the Kit handle to list before ogygia.handle().

type Rewrite = Handle & {
  check(html: string, options?: CheckOptions): Promise<RewriteCheck>;
};

RewriteKind

type

'document': a page render. 'region': a region answer (a hole, a lake remount).

type RewriteKind = "document" | "region";

RewriteResult

type

One element's render: its HTML and the sheets it needs. A string is shorthand for { html }.

type RewriteResult = string | {
  html: string;
  sheets?: readonly RewriteSheet[];
};

WholePageRewrite

type

A page rewrite: also runs on a plain string.

type WholePageRewrite = Rewrite & {
  html(html: string, ctx?: Partial<RewriteContext>): Promise<string>;
};