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
- rewrite
- CheckOptions
- CheckOptions.kind
- CheckOptions.csr
- CheckOptions.event
- ElementRewrite
- ElementRewrite.match
- ElementRewrite.render
- PageRewrite
- PageRewrite.page
- RewriteCheck
- RewriteCheck.html
- RewriteCheck.head
- RewriteCheck.restored
- RewriteCheck.failed
- RewriteCheck.dom
- RewriteCheck.mismatches
- RewriteContext
- RewriteContext.kind
- RewriteContext.csr
- RewriteContext.url
- RewriteContext.event
- RewriteContext.signal
- RewriteElement
- RewriteElement.name
- RewriteElement.html
- RewriteElement.restored
- RewriteSheet
- RewriteSheet.key
- RewriteSheet.css
- RewriteSheet.scope
- Rewrite
- RewriteKind
- RewriteResult
- WholePageRewrite
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 elementsmatchpicks go torender, 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>;
};