Preloading the engine
Download and start the Typst engine before the first document appears, so it renders at once instead of waiting for the wasm and fonts.
The engine is Typst compiled to wasm: about 6 MB of wasm and 1.4 MB of fonts (brotli), which a browser downloads, compiles and loads before the first document can render. That's about 3 seconds at 20 Mbps the first time. Later visits take them from the browser's caches until the next release. Even from the caches, the worker still has to compile the wasm, parse the fonts and lay out its first document cold: a few hundred milliseconds.
Most apps show a document only after something else: the user fills in a form, a model spends seconds writing. That
time can hide the wait. Start the engine when a document becomes likely, and the first <Typstream> finds it ready.
In React
Call preloadTypstream() when a document is likely soon:
import { preloadTypstream } from "typstream"; // or "@typstream/react"
import { edu } from "@typstream/edu";
function GenerateButton() {
return (
<button
onClick={() => {
preloadTypstream({ plugins: [edu] }); // while the model writes
generate();
}}
>
Generate
</button>
);
}It starts the page's shared engine (the one every <Typstream> without an engine uses) and runs warm-up compiles
with the plugins you name. Then it keeps the engine for a minute (holdMs). A <Typstream> that mounts in that
time renders on the warm engine and keeps it for as long as it needs it.
Or, from a component, usePreloadTypstream(when, options) keeps the engine warm while the component is mounted and
when is true. Use it for the screen that leads to the page view, such as a multi-step form or a dialog:
import { usePreloadTypstream } from "typstream";
function GenerateDialog({ open }: { open: boolean }) {
usePreloadTypstream(open, { plugins: [edu] });
// …
}typstream's versions also warm the plugins its <Typstream> adds (html-compat and universe). Pass the same
plugins as your <Typstream>s, so their packages and modules are among what gets warmed.
Two levels
level | What it does | What it costs while no document shows |
|---|---|---|
"engine" (default) | Starts the worker, compiles the wasm, loads the fonts, runs warm-up compiles with your plugins. The first document renders at once. | One worker: tens of MB of memory, until holdMs passes or release(). |
"fetch" | Downloads the wasm and base fonts into the browser's caches. No worker. | Nothing: the files wait on disk. |
Use "engine" when a document is likely within seconds or minutes, such as during a generation or on the last step
of a form. Use "fetch" early, for example at app start, when a document may come later or not at all: on the next
visit, or a few screens from now, the engine starts from the caches instead of the network.
// At app start: cheap, safe whether or not the user ever reaches a document.
preloadTypstream({ level: "fetch" });What a warm-up loads
engine.preload() (which preloadTypstream calls) compiles throwaway documents in the worker and closes them:
- A short sample with headings, bold and italic, code and math in each target (
targets, default HTML and pages). This compiles the wasm, parses the base fonts and runs the first, cold layout. - The first prompt example of each plugin in
plugins, in the first target. This loads what the plugin brings: its Typst packages, fixer and generator modules (Mermaid's diagram generator, for instance) and fonts.
All of that belongs to the worker, not the document, so it stays for the real documents that follow. To warm
something specific, such as a package your documents always import or a font they set, pass a text like your
documents instead:
preloadTypstream({ text: '#import "@preview/cetz:0.5.3"\n#set text(font: "Noto Naskh Arabic")\nمرحبا' });Without React
Create the engine early: creating it starts the worker, which downloads and compiles the wasm and loads the base
fonts. Then warm it with your plugins, and pass it to mountTypstream when the document comes.
import { createEngine, engineWorker } from "@typstream/engine";
const engine = createEngine({ spawn: engineWorker() });
void engine.preload({ plugins: [edu] });
// later
mountTypstream(element, { engine, plugins: [edu], source });prefetchEngine() from @typstream/engine/prefetch is the "fetch" level: it downloads the files without starting
a worker.
Caching
The fonts go into Cache Storage (typstream-fonts), which the worker reads first, so they download once whatever
your server sends. The wasm goes through the HTTP cache. Bundlers emit it with a content hash in its name; serve such
files with a long Cache-Control (most hosts do for hashed assets), or every visit downloads it again. See
Self-hosting the engine.
See also
Fonts and languages
The fonts the engine ships, how Arabic, Bengali and Devanagari fonts load on demand, any Google Fonts family by name, right-to-left text in both targets, and how to add fonts such as CJK.
Exports: PDF, DOCX, HTML and source
Export a rendered document as a PDF, an editable Word file, a standalone HTML file or its Typst source, in the browser or on the server, and handle export errors.