@typstream/node
Typst on the server, to validate and render documents, run the LLM fix loop, and serve the engine protocol over WebSocket.
@typstream/node runs Typst 0.15.1 on Node's worker threads, for apps that save documents a model wrote. It runs
@typstream/engine-wasm, the same build browsers run, so a document that validates on the server renders the same in
the preview. A watchdog stops runaway documents without taking the process down.
When to use it
Use it on the server, where @typstream/engine (a Web Worker) doesn't run:
- validate a document before you save it, with lint warnings for Markdown habits;
- render it to PDF, HTML or SVG pages;
- turn its diagnostics into a repair prompt and run the fix loop with your model;
- serve the engine protocol over WebSocket to browsers that shouldn't download the 6 MB engine.
For live rendering in the browser, use typstream or
@typstream/react instead. Node 20 or later is required.
Install
npm install @typstream/nodeExample
import { fixLoop, formatDiagnosticsForLLM, render, validate } from "@typstream/node";
const { ok, diagnostics } = await validate(source);
if (!ok) console.log(formatDiagnosticsForLLM(source, diagnostics));
const result = await fixLoop({
source,
generate: async ({ prompt, source }) => callYourModel(`${prompt}\n\n${source}`),
});
if (result.ok) {
const pdf = await render(result.source, "pdf");
if (pdf.ok) save(pdf.data);
}Server fix loop walks through this with a real model.
Document options
Every compile (validate, render, fixLoop) takes these options. Positions in diagnostics are UTF-16 offsets into
source, as everywhere in typstream; a diagnostic inside the preamble carries file: { path: "<preamble>" }.
Prop
Type
Documents can't read the server's filesystem or reach the network: they see only the files you pass. A file path is
relative to the document (img/a.png); paths that escape it (..) are rejected. To compile documents written in a
plugin's vocabulary, pass its preamble and files, for example @typstream/edu's:
import { eduFiles, eduPreamble } from "@typstream/edu";
import { validate } from "@typstream/node";
const result = await validate(source, {
preamble: eduPreamble,
files: eduFiles,
inputs: { showAnswers: "true" }, // the teacher's copy
});Typst Universe packages are not fetched. A document can import one only if you mount its files yourself, under its spec
(@preview/cetz:0.5.3/lib.typ and so on).
API
| Export | What it does |
|---|---|
validate(source, options?) | Compiles without exporting and adds lint warnings: { ok, diagnostics, pageCount?, ms }. |
render(source, format, options?) | Compiles and exports "pdf", "html" or "svg". |
formatDiagnosticsForLLM(source, diagnostics, options?) | A compact repair prompt in the Typst CLI's layout. |
fixLoop(options) | Validate, ask the model for a fix, repeat, and keep the best attempt. |
createEngine(options?) | A worker pool with its own fonts and budgets. |
defaultEngine() | The shared engine used when you pass none. |
createProtocolServer(options?) | The engine protocol, served from Node. |
handleWebSocket(socket, server) | Serves one WebSocket connection with a protocol server. |
validate
const validate: (source: string, options?: ValidateOptions) => Promise<ValidateResult>;Checks a finished document before it is saved: compiles it without exporting and adds @typstream/heal's lint findings
as warnings (source "heal", the rule id as code, with a hint saying what to replace). Those catch Markdown habits
that compile but render wrongly, such as **bold** or $5 and $10. It never throws for a broken document. ok is true
when there are no errors; warnings don't count.
const { ok, diagnostics, pageCount } = await validate(source, { target: "html" });Prop
Type
Prop
Type
render
const render: <F extends RenderFormat>(source: string, format: F, options?: DocumentOptions) => Promise<RenderResult<F>>;
type RenderFormat = "pdf" | "html" | "svg";Compiles and exports a document. data is PDF bytes (Uint8Array) for "pdf", an HTML document (string) for
"html", and one SVG string per page (string[]) for "svg". Diagnostics are Typst's only (no lint). ok: false
means it didn't compile and there is no data.
const pdf = await render(source, "pdf", { preamble: eduPreamble, files: eduFiles });
if (pdf.ok) await writeFile("worksheet.pdf", pdf.data);
else console.error(pdf.diagnostics);type RenderResult<F extends RenderFormat = RenderFormat> =
| { ok: true; diagnostics: Diagnostic[]; data: RenderData[F]; pageCount?: number; ms: number }
| { ok: false; diagnostics: Diagnostic[]; ms: number };
interface RenderData {
pdf: Uint8Array;
html: string;
svg: string[];
}formatDiagnosticsForLLM
const formatDiagnosticsForLLM: (source: string, diagnostics: readonly Diagnostic[], options?: FormatOptions) => string;Formats diagnostics as a compact repair prompt: a summary line, then each problem the way the Typst CLI prints it
(message, location, the source line with the span underlined, notes and hints), then instructions. Errors come first,
repeats are dropped, output is capped by maxDiagnostics and long lines are clipped, so the prompt stays small for
large documents. With no diagnostics it returns "The Typst document compiles without problems.".
const { diagnostics } = await validate("= Results\n*Total*: #hilight[12]\n");
formatDiagnosticsForLLM(source, diagnostics);The Typst document has 1 error.
error: unknown variable: hilight
--> line 2, column 11
|
1 | = Results
2 | *Total*: #hilight[12]
| ^^^^^^^
3 |
Fix every error, and the warnings where they point at a real mistake. Reply with the complete corrected Typst document only.Prop
Type
fixLoop
const fixLoop: (options: FixLoopOptions) => Promise<FixLoopResult>;Validates source; while it has errors, asks generate for a corrected document and validates that, for at most
maxRounds rounds. It returns the best attempt (fewest errors, then fewest warnings, then the latest), so a reply that
makes things worse never replaces a better one. A Markdown code fence around the model's reply is removed. With
strict, documents that only have warnings are repaired too.
FixLoopOptions extends ValidateOptions, so preamble, files, inputs, target, lint and engine
apply to every round.
const result = await fixLoop({
source,
strict: true, // also repair lint warnings such as **bold**
maxRounds: 2,
generate: async ({ prompt, source, round }) => {
const reply = await callYourModel(`${prompt}\n\n${source}`);
return reply.text;
},
});
console.log(result.ok, result.attempts.length - 1, "rounds");Prop
Type
Prop
Type
Prop
Type
Prop
Type
createEngine
const createEngine: (options?: EngineOptions) => NodeEngine;Creates an engine: a pool of worker threads, each running engine-wasm and compiling one document at a time. Create one
per process and share it; pass it as engine to the calls above. Nothing starts until the first compile. Then the wasm
module is compiled once, fonts are loaded, and workers start as needed. Workers keep Typst's caches warm between calls,
and idle workers don't keep the process alive.
import { createEngine, validate } from "@typstream/node";
const engine = createEngine({
workers: 4, // most worker threads; default min(4, cores - 1)
timeoutMs: 10_000, // watchdog per compile
fontPaths: ["/srv/fonts/noto"], // more fonts, searched recursively (like typst --font-path)
});
await validate(source, { engine });
await engine.close();Prop
Type
Prop
Type
Timeouts and crashes. A compile over budget is stopped by terminating its worker, and the result is an error
diagnostic with source: "typstream" and code: "timeout". A document that exhausts wasm memory (allocations fail at
about 2 GiB in wasm32) comes back as code: "engine-crashed". Either way the worker is replaced and the process is
unaffected. That's why typstream runs Typst as wasm rather than as a native addon, whose compiles can't be interrupted.
A worker whose memory grows past maxMemoryBytes is replaced too, since wasm memory never shrinks.
const { diagnostics } = await validate(source, { timeoutMs: 2_000 });
if (diagnostics.some((d) => d.code === "timeout")) {
// a loop that never ends, or a document far larger than usual
}Fonts. By default the engine loads Typst's bundled fonts (Libertinus Serif, New Computer Modern and DejaVu Sans
Mono, the set typst compile --ignore-system-fonts uses) and engine-wasm's script fonts (Noto Naskh Arabic, Noto Serif
Bengali and Noto Serif Devanagari, regular and bold). Unlike the browser, which downloads script fonts when a document
first needs them, the server loads them up front. Add your own with fonts (bytes) or fontPaths (directories). See
Fonts and languages.
Prop
Type
defaultEngine
const defaultEngine: () => NodeEngine;The engine validate, render, fixLoop and createProtocolServer use when you don't pass one. It is created on
first use with default options.
createProtocolServer
const createProtocolServer: (options?: ProtocolServerOptions) => ProtocolServer;Serves typstream's engine protocol (the one @typstream/core defines and the browser worker speaks) from Node, so a
browser can render through your server instead of downloading the engine. It is @typstream/engine's own server code,
over an adapter that compiles on this package's worker pool. Remote engine shows the
client side.
import { WebSocketServer } from "ws";
import { createProtocolServer, handleWebSocket } from "@typstream/node";
const server = createProtocolServer({ timeouts: { streaming: 3_000, final: 10_000 }, maxDocuments: 32 });
new WebSocketServer({ port: 8080, maxPayload: 8 << 20 }).on("connection", (ws) => handleWebSocket(ws, server));- Sessions. Each connection is a session with its own documents. Closing it cancels its queued requests and frees its documents.
- What it offers. The HTML and paged targets (paged with changed-page updates), and PDF and HTML exports. No
resolve/*requests. - Untrusted clients. Messages are checked before the server reads them; malformed requests, too many documents or
too long a text get an
invalid-paramserror. Clients can't make the server fetch packages or load fixer modules, and the fonts and packages a client sends ininitializeordocument/openare ignored: the server uses its engine's fonts. - Watchdog. Documents live on the main thread and workers only compile, so a watchdog kill costs one compile, not the session.
Prop
Type
Prop
Type
Prop
Type
To serve the protocol over another transport, call server.connect(send) yourself and feed each client message to the
connection's receive.
handleWebSocket
const handleWebSocket: (socket: WebSocketLike, server: ProtocolServer) => ProtocolConnection;Serves one WebSocket. Each text message is a client message in the protocol's wire format: JSON, with bytes as
{ "$bytes": "<base64>" } (serializeMessage and deserializeMessage from @typstream/core read and write it).
Replies go back the same way, and the connection closes with the socket. ws's WebSocket fits WebSocketLike, and
so does anything with the same on, send and close. Cap message sizes on the socket server (ws's maxPayload).
Prop
Type
See also
- Getting started on Node: a first validate-and-render script.
- Server fix loop: validate, repair with a model, render.
- Remote engine: browsers that render through your server.
- Security: what documents can and can't reach.
- @typstream/engine-wasm: the compiler this package runs.
@typstream/heal
The self-healing parser that turns any prefix of streamed Typst into a source that parses, with lint fixes for Markdown habits.
@typstream/edu
The Typst vocabulary for teachers' documents (templates, questions, answers and keys, callouts, rubrics, drawings, chemistry) as a typstream plugin with a prompt kit.