typstream

Writing a plugin

Package your own Typst functions, styles, prompt rules and compile fixes as a typstream plugin, and load it in React, the DOM renderer or the engine.

A plugin is one plain object with a key and any of a set of optional facets. Each typstream package reads the facets it understands and ignores the rest, so a plugin written for the renderer keeps working when new packages (the editor) add facets of their own. @typstream/html-compat, @typstream/universe and @typstream/edu are plugins; so are a school's branded templates or a chemistry pack.

import { definePlugin } from "@typstream/core";

export const chemistry = definePlugin({
  key: "acme/chemistry", // unique; namespace third-party keys
  version: "1.0.0",
  dependencies: ["edu"], // keys of plugins that must load too, before this one
  engine: {
    files: { "@acme/chemistry:1.0.0/lib.typ": LIB, "@acme/chemistry:1.0.0/typst.toml": TOML },
    preamble: '#import "@acme/chemistry:1.0.0": *',
  },
  stylesheets: [CSS],
});

definePlugin only type-checks the literal; a plugin needs no runtime from typstream. For the concepts behind plugins, see Plugins.

Using plugins

// React: on a provider (every document below it) or on one <Typstream>.
<TypstreamProvider plugins={[edu, chemistry]}>…</TypstreamProvider>

// Without a framework.
mountTypstream(element, { engine, source, plugins: [edu, chemistry] });

// The engine alone (Node, a custom renderer).
const doc = engine.open({ plugins: [edu, chemistry] });

typstream's <Typstream> adds htmlCompat and universe before the plugins you give it (turn them off with htmlCompat={false} and packages={false}).

Build a plugin step by step

The example below is a small chemistry pack: one Typst function, #reaction, that shows an equation with the conditions it needs. It works in both render targets, is styled for the HTML target, tells the model how to use it, and comes with a fixer for a common mistake.

typst.toml
lib.typ
embed.mjs
chemistry.css
index.ts
fixers.js
assets.generated.ts

Write the Typst side as a local package

A typst.toml and an entry point make the files a Typst package. Documents import it by name, and the same files work with the native CLI (typst compile --package-path), so you can test them outside typstream.

typst/typst.toml
[package]
name = "chemistry"
version = "1.0.0"
entrypoint = "lib.typ"
compiler = "0.15.1"
typst/lib.typ
/// A labelled reaction: the equation, with what it needs after it.
///
/// - conditions (content, none): What the reaction needs, e.g. heat.
#let reaction(conditions: none, body) = context {
  if target() == "html" {
    html.elem("div", attrs: (class: "acme-reaction"), {
      body
      if conditions != none { html.elem("span", attrs: (class: "acme-conditions"), conditions) }
    })
  } else {
    block(inset: 6pt, stroke: 0.5pt + gray, radius: 3pt, {
      body
      if conditions != none { h(1em); text(size: 0.85em, fill: gray)[(#conditions)] }
    })
  }
}

context target() tells the HTML target from the paged one, so each gets output that suits it: semantic HTML with classes your stylesheet styles, and Typst layout for pages and PDF.

Style the HTML

Scope rules to the renderer's root (.typstream) and wrap them in :where(), so their specificity is zero and an app's own rules win without !important. Use the theme's custom properties so dark mode works.

css/chemistry.css
:where(.typstream .acme-reaction) {
  display: flex;
  align-items: baseline;
  gap: 1em;
  margin-block: 0.8em;
  padding: 0.4em 0.8em;
  border: 1px solid var(--typstream-muted);
  border-radius: 4px;
}
:where(.typstream .acme-conditions) {
  color: var(--typstream-muted);
  font-size: 0.85em;
}

Embed the files

The engine mounts files you give it as strings or bytes, and the renderer takes CSS as strings. Any build step that turns the files into a module works; this script needs nothing but Node:

scripts/embed.mjs
// Writes src/assets.generated.ts from typst/ and css/. Run it after every change to them.
import { readdirSync, readFileSync, writeFileSync } from "node:fs";

const files = Object.fromEntries(readdirSync("typst").map((name) => [name, readFileSync(`typst/${name}`, "utf8")]));
const css = readFileSync("css/chemistry.css", "utf8");
writeFileSync(
  "src/assets.generated.ts",
  `export const FILES: Record<string, string> = ${JSON.stringify(files, null, 2)};\n` +
    `export const CSS: string = ${JSON.stringify(css)};\n`,
);

With Vite you can import them directly instead (import LIB from "../typst/lib.typ?raw").

Write a fixer module (optional)

Fixers run in the engine worker after a compile fails, and turn an error into edits that make it go away. Because the worker can't receive functions, a plugin ships them as an ES module your app serves, referenced by URL. This one writes an unknown #name as the plain word, so a misspelt function doesn't break the rest of the document:

src/fixers.js
// Default export: a fixer or an array of them.
export default {
  name: "acme/unknown-as-text", // `#foo` with no `foo` defined: write the word
  match: /^unknown variable: (\w+)$/,
  fix: (d, ctx) => (d.span ? [{ from: d.span.from - 1, to: d.span.to, insert: ctx.text.slice(d.span.from, d.span.to) }] : null),
};

Define the plugin

src/index.ts
import { definePlugin } from "@typstream/core";
import { CSS, FILES } from "./assets.generated";

const ROOT = "@acme/chemistry:1.0.0";

export const chemistry = definePlugin({
  key: "acme/chemistry",
  version: "1.0.0",
  engine: {
    // `@ns/name:x.y.z/path` keys make a local Typst package: importable by name, nothing downloaded.
    files: Object.fromEntries(Object.entries(FILES).map(([name, text]) => [`${ROOT}/${name}`, text])),
    preamble: `#import "${ROOT}": *`,
    fixerModules: [new URL("./fixers.js", import.meta.url).href],
  },
  // The renderer drops classes nobody listed, so the page's own can't style a document.
  sanitize: { allowClasses: ["acme-*"] },
  stylesheets: [CSS],
  prompt: {
    catalogue: [
      {
        name: "reaction",
        signature: "reaction(conditions: content, body: content) -> content",
        description: "A chemical reaction, with what it needs (heat, a catalyst) after it.",
        example: "#reaction(conditions: [heat])[$2 H_2 + O_2 -> 2 H_2 O$]",
      },
    ],
    rules: ["Write every chemical reaction with `#reaction`; never draw the arrow and conditions by hand."],
  },
});

Ship fixers.js next to the built index.js (copy it into dist/): the new URL(…, import.meta.url) resolves next to the module, and the app's bundler emits the file as an asset.

The prompt facet describes your Typst API to the model. buildSystemPrompt(plugins) from @typstream/edu (beta) turns plugins' prompt facets into a system prompt; see Prompting.

Use it

import { Typstream } from "typstream";
import { chemistry } from "@acme/chemistry";

<Typstream source={text} isStreaming={streaming} plugins={[chemistry]} />;

The model can now write #reaction(conditions: [heat])[$2 H_2 + O_2 -> 2 H_2 O$] with no import of its own: the plugin's preamble imports the package before every document.

Facets

FacetRead byWhat it does
heal.handlersheal (main thread)HealHandlers: product-specific fixes on settled text (settled) or on the healed source (output). The only facet that holds functions.
heal.linthealOverrides built-in lint rules by id: { "currency-dollar": "fix" }. Later plugins and the document's own heal.lint win.
engine.filesengineFiles mounted for every document. Keys of the form @ns/name:x.y.z/path make a local Typst package, importable with no download.
engine.preambleengineTypst evaluated before the document, after earlier plugins' preambles and before a template's and the app's.
engine.packagesengineTypst Universe packages the document may import (an allowlist entry: name, version, URL, integrity). Fetched only when imported. Beta.
engine.fixerModulesengine workerES module URLs whose default export is a DiagnosticFixer or an array of them. Loaded inside the worker, once per URL.
engine.generatorModulesengine workerES module URLs whose default export is a FileGenerator or an array of them: files made from the document's source before every compile, for what Typst can't compute (@typstream/mermaid draws diagrams with pele). Loaded inside the worker, once per URL. Beta.
engine.fontsengine workerFonts for the engine. Worker-wide: see below. Beta.
templatesdom, reactNamed document setups (template="worksheet"): a preamble and default sys.inputs. A later plugin's template replaces an earlier one's of the same name.
sanitizedomExtra tags, attributes and classes the HTML sanitizer lets through. Scripts, event handlers and URL-loading attributes stay blocked whatever a plugin says.
stylesheetsdomCSS for the HTML your Typst writes, injected next to the renderer's and included in standalone HTML exports.
promptyour appThe function catalogue, rules and few-shot examples to tell the model about your Typst API. A planned @typstream/ai package will read it too.
islandsThe HTML renderer, @typstream/reactInteractive components mounted over markers your Typst writes, by name, with parse to check their data. See Writing an island. Beta.
editor(future editor)Reserved; typed loosely so plugins can fill it in early. Beta.

The full type:

Prop

Type

Beta facets

engine.packages, engine.fonts, engine.generatorModules, islands and editor are beta: their shape may change before 1.0.

What runs where

Everything except heal.handlers and islands' parse is plain data. The engine facet is posted to the worker, which can't receive functions, so it must stay structured-clonable: code that runs in the worker is referenced by URL (engine.fixerModules, engine.generatorModules).

A document's plugins bring their files, packages, preamble, heal handlers and lint settings, and their fixer and file generator modules, which the worker loads for that document only. A module that fails to load is logged (an engine log event) and the document compiles without it.

Fonts belong to the worker, not to a document: give a plugin with engine.fonts to the engine itself.

const engine = createEngine({ spawn: engineWorker(), plugins: [bengali] }); // fonts, packages, fixer modules

<TypstreamProvider engine={engine} plugins={[bengali]}>…</TypstreamProvider>;

The engine's plugins' fonts, packages and fixer modules are sent when each worker starts, so every worker (including replacements after a watchdog restart) has them. A document whose plugin brings fonts the engine doesn't have logs a warning once per plugin. See Fonts and languages.

Order, duplicates and errors

Order. Plugins load in the order given, except that a plugin always comes after its dependencies: a dependency listed later moves up to just before the first plugin that needs it. Order matters where facets add up: preambles run in that order, a later plugin's file replaces an earlier one's at the same path, and later stylesheets come later in the cascade.

Duplicates. A key given more than once loads once, as its last definition, at the place of its first. A provider's plugin can be overridden by a component's with the same key.

Errors. A dependency that isn't among the plugins, a cycle, or a plugin without a key throws when the document opens. resolvePlugins from @typstream/core does the resolution, if you want to check a list yourself:

import { resolvePlugins } from "@typstream/core";

resolvePlugins([chemistry, edu]).map((p) => p.key); // ["edu", "acme/chemistry"]: edu moved up before its dependent

Writing the Typst side

  • Mount it as a local package (@acme/chemistry:1.0.0/… keys with a typst.toml), so documents and exported sources can #import it by name and the same files work with native typst --package-path.
  • Expect cut-off input. The model's output is compiled after every token. Give every named parameter a default, and accept what a stream cut leaves: (2 arrives as 2, 5em as 5. @typstream/edu's sources show patterns for this.
  • Branch on the target with context target() where the HTML and paged output should differ, and write semantic HTML with classes your stylesheets style.
  • Keep CSS overridable. Scope rules to the renderer's root and keep their specificity at zero, so apps can override them: :where(.typstream .acme-formula) { … }. Follow the theme's custom properties (--typstream-foreground, --typstream-muted, --typstream-link, …) so dark mode works. See Theming.
  • Allow only what you write. If your HTML needs a tag or attribute the sanitizer drops, list exactly those in sanitize ({ allowTags: ["details"], allowAttrs: { details: ["open"] } }). The "*" key allows attributes on every HTML element ({ allowAttrs: { "*": ["data-step"] } }); SVG and MathML keep their own lists, and URL attributes (href, src) are allowed only by tag, where the sanitizer checks their URLs. An allowed name gets the renderer's id prefix, like id.
  • Declare your classes. The sanitizer drops classes it doesn't know, so a document can't borrow the page's. List the ones your Typst writes in sanitize.allowClasses, by name or by a prefix of your own (["quiz-*"], as edu does with edu-*), and style only those.

Writing a fixer module

When a compile fails, the worker offers each error to its fixers in priority order; the first that returns edits fixes it. A round of fixes is applied only when every error has one, then the worker recompiles, at most twice per revision.

Prop

Type

fix returns edits against ctx.text (the document without its preamble), or null. Edits are { from, to, insert } in UTF-16 offsets, non-overlapping and ascending. fix may be async, for example to fetch something; the compile waits for it.

Prop

Type

  • Priority. Default 50. The built-in pending-ref runs at 10 and the catch-all tail-cut at 100, so most fixers run between them.
  • Modes. modes: ["streaming"] keeps a fixer out of final compiles, for fixes that only make sense while text is still arriving. Use ctx.settled to leave text that is still being typed alone, or to change only it.
  • Errors. A fixer that throws is skipped.
  • Reporting. While streaming, the errors a fixer fixed are reported as info diagnostics whose source is the fixer's name. In final mode the output is the fixed one, but the error is still reported as an error, so the finished document's diagnostics show what the model got wrong. fixersApplied in the compiled event names it either way.
  • Placeholders. Fixed compiles import typstream's runtime library as typstream, so a fix can insert its placeholders, such as #typstream.pending-ref("key");.

To add fixers to every document rather than through a document's plugins, pass the module to the engine: createEngine({ spawn: engineWorker(), initialize: { fixerModules: [url] } }). To replace the built-in list, write your own worker (Self-hosting).

Fixer modules are code

Importing a module runs it in the worker. A server that faces untrusted clients must not load modules they name; @typstream/node's protocol server ignores them. See Security.

Matching the PDF and Word

A document looks the same three ways: in the paged view, in the PDF from exportPdf(), and in the Word file from exportDocx() (beta), which stays editable. The first two draw the same laid-out pages. The DOCX is rebuilt from them as Word paragraphs, tables, equations and pictures, and a layout engine lays it out again. A plugin's components have to survive that, so write them from what Word can express:

  • Text, paragraphs and tables come through as they are, line for line: the engine's layout profile keeps Typst's lines where Word puts them (a constant line pitch, ragged right, no hyphenation, rows that don't split). Don't set par(leading: …), par(justify: true) or a breakable table row in your Typst; heal's lint takes them out of documents anyway.
  • Boxes and blocks with square corners, strokes and fills become one-cell tables or bordered paragraphs. A rounded corner or rotated text with text inside can't be one: it becomes a picture of the box, and the export warns (docx/fallback). Prefer square frames, as edu's callouts are.
  • A blank to write on is underlined space in Word, and Word draws an underline at the font's underline position: about 0.08em below the baseline. The export raises or lowers an empty blank so its underline lands on the line Typst drew, but not one with text on it (a shown answer), which would move with it: draw the line at the underline position in Typst (edu's blank is a box with stroke: (bottom: …) and outset: (bottom: 0.078em)), and keep it on a line of text: a box alone in a cell has a line of its own, shorter than a text line, unless something before it (a word joiner, #sym.wj) makes it one.
  • A rule across the column (a line to write on) is a paragraph with a bottom border, at the bottom of its line.
  • Equations are Word math; each engine sets it a little differently.
  • Drawings (CeTZ, curves, a mind map) become pictures: an SVG with a PNG, the same size and place. Give them a description for screen readers (a <typstream-drawing> marker, as edu's drawings do).

The conformance suite

This repository's plugins prove it with a shared suite (tools/conformance) run on their own examples: edu's catalogue, templates and examples with answers hidden and shown, mindmap's examples, and a few documents using each of Universe's packages. For each example:

CheckWherePasses when
Paged view = PDFa browser (vitest)every page painted in the document panel matches pdf.js's raster of the PDF: no more than 4 differing pixels touching
DOCX is validNodeMicrosoft's Open XML validator reports no errors
DOCX = PDFNode, LibreOfficeevery line and page start is Typst's (by their text around equations, where the example has some), pictures match the PDF's pixels, every equation's letters and digits come out, and rules, borders and shading are where Typst draws them (no more than 6 differing pixels touching)

A plugin in this repository adds three files and two vitest projects:

__tests__/conformance/suite.ts
import { type ConformanceSuite, withInputs } from "@typstream/conformance";
import { chemistry, chemistryCatalogue } from "../../src/index";

export const suite: ConformanceSuite = {
  name: "chemistry",
  plugins: [chemistry],
  examples: withInputs(
    chemistryCatalogue.map((d) => ({ name: d.name, source: d.example ?? "" })),
    [{ showAnswers: "false" }, { showAnswers: "true" }],
  ),
};
__tests__/conformance/paged.test.ts
import { pagedConformance } from "@typstream/conformance/paged";
import { suite } from "./suite";

pagedConformance(suite);
__tests__/conformance/docx.test.ts
import { docxConformance } from "@typstream/conformance/docx";
import { suite } from "./suite";

docxConformance(suite);
vitest.config.ts
import { defineConfig } from "vitest/config";
import { conformanceProjects } from "../../tools/conformance/src/vitest.mjs";

const alias = { "@typstream/core": new URL("../core/src/index.ts", import.meta.url).pathname };

export default defineConfig({
  test: {
    projects: [{ test: { name: "node", include: ["__tests__/*.test.ts"] } }, ...conformanceProjects(alias)],
  },
});

pnpm test:paged (vitest run --project paged) runs the first in Chromium (BROWSERS=firefox for another). pnpm test:docx runs the second; it needs LibreOffice and poppler on PATH, and uses Microsoft's validator where it is built (dotnet publish tools/docx-check/validator -c Release -o tools/docx-check/validator/out). CI runs both on every pull request. A failure names the example, the DOCX it wrote (under $TMPDIR/typstream-conformance/) and what differs: the first line laid out differently, or where on the page a rule, a border or a picture is off.

The suite is part of this repository, not a published package. To check a plugin of your own, export its examples with exportPdf() and exportDocx(), open the DOCX in Word or LibreOffice, and compare the pages with the PDF's.

Testing a plugin

Open a document with your plugin on a real engine and check what it renders, as typstream's own contract tests do. In Node, @typstream/engine/server's inProcess runs the worker on the calling thread:

test-plugin.mjs
import { readFileSync } from "node:fs";
import { createEngine } from "@typstream/engine";
import { engineWasm, inProcess } from "@typstream/engine/server";
import { baseFonts } from "@typstream/engine-wasm/fonts";
import { chemistry } from "./dist/index.js";

const wasm = readFileSync(new URL(import.meta.resolve("@typstream/engine-wasm/engine_bg.wasm")));
const fonts = baseFonts.map((url) => new Uint8Array(readFileSync(url)));
const engine = createEngine({ spawn: inProcess(() => engineWasm({ wasm, fonts })), spare: false });

const doc = engine.open({ plugins: [chemistry], target: "html" });
doc.onEvent((event) => {
  if (event.type === "compiled") console.log(event.status, event.fixersApplied);
});
doc.set("#reaction(conditions: [heat])[$2 H_2 + O_2 -> 2 H_2 O$] and #foo here");
doc.finish();

const state = await new Promise((resolve) => {
  const stop = doc.subscribe((s) => {
    if (s.status === "done" || s.status === "error") (stop(), resolve(s));
  });
});
console.log(state.status, state.diagnostics.map((d) => d.message), state.artifact?.html.includes("acme-reaction"));
engine.dispose();

Here fixersApplied lists acme/unknown-as-text for unknown variable: foo, and the HTML contains the acme-reaction element. Test the paged target the same way (target: "paged"), and stream the document in chunks with doc.push() to see that every prefix renders.

inProcess is beta

inProcess blocks the calling thread while it compiles, and the watchdog can't stop a runaway compile there. Use it for tests and scripts, not to serve users.

On this page