typstream

Running the engine on a server

Serve typstream's engine protocol over WebSocket with @typstream/node, so browsers render live previews without downloading the 6 MB compiler, and connect the browser client to it.

By default each browser runs Typst itself, in a worker: a 6.2 MB download (brotli) before the first preview. @typstream/node can run the engine on your server instead and serve the same protocol over WebSocket. The browser still heals the stream and renders the result; only compiling moves to the server.

Consider it for devices too slow or too constrained for the wasm engine, or for pages that show a document once and don't justify the download. The cost is a round trip per compile and compile time on your servers.

Beta

The browser client, fromWebSocket, is beta and may change before the first stable release. Switching from server previews to the local engine once its download finishes isn't built yet.

Serve the protocol

npm install @typstream/node ws
server.ts
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));

createProtocolServer runs @typstream/engine's protocol server, the same code that runs in the browser worker, over an adapter that compiles on @typstream/node's worker pool. handleWebSocket attaches one socket to it; anything with ws's on, send and close works.

To share a port with your HTTP server and decide who may connect, handle the upgrade yourself. typstream doesn't authenticate connections:

server.ts
import { createServer } from "node:http";
import { WebSocketServer } from "ws";
import { createEngine, createProtocolServer, handleWebSocket } from "@typstream/node";

const engine = createEngine({ workers: 4 });
const typst = createProtocolServer({ engine });
const wss = new WebSocketServer({ noServer: true, maxPayload: 8 << 20 });

const http = createServer(app); // your app's request handler
http.on("upgrade", (req, socket, head) => {
  if (req.url !== "/typst" || !isSignedIn(req)) {
    socket.destroy();
    return;
  }
  wss.handleUpgrade(req, socket, head, (ws) => handleWebSocket(ws, typst));
});
http.listen(3000);

The options:

Prop

Type

The engine's own options (workers, fonts, the default budget) are createEngine's; see Validating and repairing on the server. One engine can serve the protocol and your validate and render calls at the same time.

What the server offers

TargetsHTML, and paged with changed-page updates (only pages whose content changed are sent).
ExportsPDF and HTML: doc.exportPdf() and doc.exportHtml() work over the connection.
Fixers and fallbackThe built-in fixers and the fallback ladder run on the server, as they do in the browser worker.
FontsThe server engine's: Typst's bundled fonts and the script fonts, plus any you give createEngine. Fonts a client sends are ignored.
PackagesNone by default. The server ignores the package lists clients send (see below) and has no allowlist of its own, so #import "@preview/…" reports that the package isn't allowed. Local packages in a plugin's files, such as @typstream/edu's, work.
Fixer modulesIgnored, with a warning: importing a module would run the client's code on your server.
resolve/*Not offered.

Sessions. Each connection is a session with its own documents. Closing the socket cancels its queued requests and frees its documents.

Watchdog. Documents live on the server's main thread and pool workers only compile, so a compile over budget costs one compile, not the session: the pool terminates that worker and the compile answers with an error diagnostic, code: "timeout" (or "engine-crashed" when it ran out of memory). The fallback then finds the block that hangs and shows it as an error box.

The wire format

Messages are JSON text, one per WebSocket message. They are the protocol's plain data (@typstream/core's ClientMessage and ServerMessage), except that bytes (files, PDF exports) are written as { "$bytes": "<base64>" }. serializeMessage and deserializeMessage from @typstream/core read and write it, in the browser and in Node:

import { deserializeMessage, serializeMessage } from "@typstream/core";

serializeMessage({ id: 1, method: "export/pdf", params: { uri: "doc-1", rev: 3 } });
// '{"id":1,"method":"export/pdf","params":{"uri":"doc-1","rev":3}}'
deserializeMessage('{"id":1,"result":{"uri":"doc-1","rev":3,"diagnostics":[],"status":"ok","data":{"$bytes":"JVBERi0="}}}');
// result.data is a Uint8Array

deserializeMessage only parses: validate the result before trusting it, as the server does.

Untrusted clients

Anyone who can open the socket can send the server anything, so the server treats every client as untrusted:

  • Shapes are checked before the protocol server reads a message. A malformed request is answered invalid-params; anything else malformed gets a $/log warning back and is dropped. The only notification clients may send is $/cancel.
  • Limits. More than maxDocuments open documents (32), or a document longer than maxTextLength (1,000,000 UTF-16 code units, preamble and text), answers invalid-params. Cap the size of a single message on the socket server: ws's maxPayload (8 MiB above).
  • No fetching for clients. The protocol server runs with trustClient: false, so it ignores the package allowlists clients send. Otherwise a client could make your server fetch any URL.
  • No code from clients. It runs with clientFixers: false, so it ignores the fixer modules clients name. Otherwise a client could run code in your server (a data: URL is a module).
  • The sandbox. Documents can't read the server's filesystem or the network, only the files the client sent to that document, and diagnostics name virtual paths only. See Security.

Authentication, rate limits and the number of connections per user are yours to enforce, in the upgrade handler or in front of the server.

Connect the browser

The engine client (createEngine from @typstream/engine) talks to whatever its spawn function starts. In a browser that is usually a worker (engineWorker()); fromWebSocket from @typstream/engine/websocket connects it to your server instead:

npm install @typstream/engine
engine.ts
import { createEngine } from "@typstream/engine";
import { fromWebSocket } from "@typstream/engine/websocket";

export const engine = createEngine({ spawn: fromWebSocket("wss://typst.example.com/typst") });

Then use it like any engine: <TypstreamProvider engine={engine}> in React, or mountTypstream(element, { engine, … }). In an app rendered on the server, create the engine in the browser only, as in Self-hosting. fromWebSocket is its own entry point, so pages that compile in a worker don't download it.

To authenticate each connection with a short-lived token, pass a function: it is called for every connection, the first and each one that replaces it, and must return the URL synchronously.

// sessionToken() returns your app's current token.
const spawn = fromWebSocket(() => `wss://typst.example.com/typst?token=${encodeURIComponent(sessionToken())}`);

How the client behaves over this transport:

  • Healing stays in the browser. The client heals each chunk on the main thread and sends the server one diff right before each compile, so the server sees healed source, never half a token.
  • The watchdog. The budgets fromWebSocket gives the engine, 10 s streaming and 30 s final, sit above the most the server takes with its default timeouts (about 4.5 s and 15 s, its fallback included), so the server's own timeout answers first: a timeout diagnostic that costs one compile. Past the client's budget (a server that stopped answering), the client closes the connection and opens a new one, a new session; documents open themselves again before their next compile. If you raise the server's timeouts, raise the client's watchdog with them.
  • No spare connection. In a worker the engine keeps a spare warm; over a socket that would be a second session per page, so fromWebSocket turns it off. Pass spare: true to createEngine to have it anyway.
  • Dropped connections. When a connection closes (the server restarted, a proxy timed it out), the engine emits a disconnect event and opens a new one; the compile or export that was running is retried there, without counting against the document. A request that keeps dropping the connection (three times in a row, such as a message over maxPayload) then counts as a crash, so it stops.
  • A server that can't be reached. Opening a connection is retried 4 times, after 0.5, 1, 2 and 4 s (retries, retryDelayMs). When every attempt fails, or a connection closes before the server answers initialize (it refused it), the engine fails (an engine failed event, every document in error) rather than reconnecting in a loop. Create a new engine to try again.
  • Telemetry works as with a worker: the events come from the client. serverInfo.name in the engine's ready event is @typstream/node.

The options:

Prop

Type

The server's $/log warnings (ignored fonts or fixer modules) arrive as log events. Browsers can't send WebSocket pings, so a proxy that closes idle connections (nginx's proxy_read_timeout is 60 s by default) makes the client reconnect after each one: harmless, as nothing is lost, but raise the proxy's idle timeout if the reconnects bother you.

Content-Security-Policy

Under a policy, allow the socket's origin in connect-src:

connect-src 'self' wss://typst.example.com

If no page uses the local engine, 'wasm-unsafe-eval' and worker-src aren't needed for typstream. See Security for the rest of the policy.

On this page