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.
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.
[package]
name = "chemistry"
version = "1.0.0"
entrypoint = "lib.typ"
compiler = "0.15.1"/// 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.
: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:
// 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:
// 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
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
| Facet | Read by | What it does |
|---|---|---|
heal.handlers | heal (main thread) | HealHandlers: product-specific fixes on settled text (settled) or on the healed source (output). The only facet that holds functions. |
heal.lint | heal | Overrides built-in lint rules by id: { "currency-dollar": "fix" }. Later plugins and the document's own heal.lint win. |
engine.files | engine | Files mounted for every document. Keys of the form @ns/name:x.y.z/path make a local Typst package, importable with no download. |
engine.preamble | engine | Typst evaluated before the document, after earlier plugins' preambles and before a template's and the app's. |
engine.packages | engine | Typst Universe packages the document may import (an allowlist entry: name, version, URL, integrity). Fetched only when imported. Beta. |
engine.fixerModules | engine worker | ES module URLs whose default export is a DiagnosticFixer or an array of them. Loaded inside the worker, once per URL. |
engine.generatorModules | engine worker | ES 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.fonts | engine worker | Fonts for the engine. Worker-wide: see below. Beta. |
templates | dom, react | Named document setups (template="worksheet"): a preamble and default sys.inputs. A later plugin's template replaces an earlier one's of the same name. |
sanitize | dom | Extra tags, attributes and classes the HTML sanitizer lets through. Scripts, event handlers and URL-loading attributes stay blocked whatever a plugin says. |
stylesheets | dom | CSS for the HTML your Typst writes, injected next to the renderer's and included in standalone HTML exports. |
prompt | your app | The function catalogue, rules and few-shot examples to tell the model about your Typst API. A planned @typstream/ai package will read it too. |
islands | The HTML renderer, @typstream/react | Interactive 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 dependentWriting the Typst side
- Mount it as a local package (
@acme/chemistry:1.0.0/…keys with atypst.toml), so documents and exported sources can#importit by name and the same files work with nativetypst --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:
(2arrives as2,5emas5.@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 yourstylesheetsstyle. - 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 allowednamegets the renderer's id prefix, likeid. - 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 withedu-*), 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-refruns at 10 and the catch-alltail-cutat 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. Usectx.settledto 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
infodiagnostics whosesourceis 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.fixersAppliedin thecompiledevent 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
blankis a box withstroke: (bottom: …)andoutset: (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:
| Check | Where | Passes when |
|---|---|---|
| Paged view = PDF | a 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 valid | Node | Microsoft's Open XML validator reports no errors |
| DOCX = PDF | Node, LibreOffice | every 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:
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" }],
),
};import { pagedConformance } from "@typstream/conformance/paged";
import { suite } from "./suite";
pagedConformance(suite);import { docxConformance } from "@typstream/conformance/docx";
import { suite } from "./suite";
docxConformance(suite);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:
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.
Telemetry and events
What typstream reports about each compile and render, where to listen for it, and how to send it to your own analytics without collecting documents.
Writing an island
Mount an interactive component over a drawing a Typst function writes, a render island, with the Typst drawing as its fallback for print, PDF and renderers without it.