Reference
Renderer port
The Renderer, RenderTargetInfo and RenderInput types, the render routes and events, and the createRenderer and markdownTarget adapter.
The server types come from packages/editor/src/server/ports.ts (@skaile/forge-editor/server), the wire types from packages/editor/src/core/backend-types.ts (@skaile/forge-editor/core), the adapter from @skaile/forge-editor/adapters/render. For how to add a target and what the editor shows, see Render.
Renderer
EditorPorts.render (capability render). The result is stored through EditorPorts.assets; without it POST /api/editor/render answers 501.
| Member | Type | Meaning |
|---|---|---|
targets | (user: object) => Promise<RenderTargetInfo[]> | The targets this user may use. |
render | (target, input, user, progress, signal) => Promise<{ data: Uint8Array, mime: string, fileName: string }> | Renders input to target. progress is a RenderProgressReporter ((p: RenderProgress) => void); signal aborts when the client goes away. Throw to fail the render: the message reaches the client. |
RenderTargetInfo
| Field | Type | Meaning |
|---|---|---|
id | string | Unique among the targets of one renderer. |
label | string | Already in the user's language. |
accepts | readonly string[] | Block type ids, or 'document' for a whole Document. |
mime | string | MIME type of the result. |
RenderInput
| Field | Type | Meaning |
|---|---|---|
documentId | string | The Document the result is stored under. |
blockId | string? | Set for a Block; absent for the whole Document. |
content | JSONContent | The Block's TipTap JSON, or the whole Document without blockId. |
options | Record<string, unknown>? | Target specific options. |
Routes
Route (API key) | Request | Answer |
|---|---|---|
GET /api/editor/render/targets (renderTargets) | none | RenderTargetInfo[] |
POST /api/editor/render (renderPost) | { target: string, input: RenderInput } | SSE: progress { phase: string, percent?: number }, then done { asset: string, fileName: string, mime: string } or error { message: string } |
Both routes are served only when ports.render is present. Refusals before the stream starts: 400, 401, 403, 404 (unknown target), 422 (the target does not accept the Block type), 501 (no assets port).
EditorBackend['render']
| Member | Type | Meaning |
|---|---|---|
targets | (signal?) => Promise<RenderTargetInfo[]> | The targets of the user. |
render | (target, input, { onProgress?, signal? }?) => Promise<RenderResult> | Streams one render. RenderResult is RenderDone (asset, fileName, mime) plus url of the stored asset. Rejects with the server's message when the render fails. |
@skaile/forge-editor/adapters/render
| Export | Meaning |
|---|---|
createRenderer(targets) | A Renderer over a list of RenderTargets. A repeated id keeps the first; render rejects with 404 for an unknown id. |
RenderTarget | RenderTargetInfo plus run(input, progress, signal). |
markdownTarget(options?) | The built-in target markdown (text/markdown); options schema, blockTypes, label. |