# 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.

Source: https://typstream.vercel.app/docs/guides/fonts-and-languages

The engine compiles with its own fonts, not the reader's system fonts, so a page looks the same on every machine and
in the exported PDF. It ships a small base set and downloads fonts for other scripts only when a document uses them.
This page covers both, letting documents use any Google Fonts family, right-to-left text, and how to add fonts of
your own.

## The fonts the engine ships

| Fonts | Covers | Loaded |
|---|---|---|
| Libertinus Serif (regular, bold, italic) | Latin, Greek, Cyrillic, Hebrew | When the engine starts |
| New Computer Modern Math | Math | When the engine starts |
| DejaVu Sans Mono | Raw text and code | When the engine starts |
| The rest of Typst's bundled faces: Libertinus Serif bold italic and semibold, New Computer Modern, the math font's regular and bold, DejaVu Sans Mono bold and oblique | What a document asks for (`*_bold italic_*`, bold code, math in bold text, symbols Libertinus Serif lacks) | The first time a document uses it |
| Noto Naskh Arabic (regular, bold) | Arabic | The first time a document uses it |
| Noto Serif Bengali (regular, bold) | Bengali | The first time a document uses it |
| Noto Serif Devanagari (regular, bold) | Devanagari (Hindi, Marathi, Nepali, …) | The first time a document uses it |

The base fonts are about 2.6 MB. Each script font file is 47–79 KB compressed and is fetched on its own, so a
document with regular-weight Arabic text downloads one file. All of them are served from your own origin: your
bundler emits them as assets next to `@typstream/engine-wasm`'s JavaScript. Their licenses are in
`@typstream/engine-wasm`'s `dist/fonts/NOTICE` and `dist/fonts/LICENSE-Noto.txt`.

```typst
#set text(size: 16pt)

Good morning, class.

#text(lang: "ar")[صباح الخير يا طلاب.]

#text(lang: "bn")[সুপ্রভাত, শিক্ষার্থীরা।]
```

On a first visit you may see the Arabic and Bengali lines in the **Pages** view settle a moment after the English one:
the first compile lacked their fonts, and the engine compiled again once they arrived.

## How lazy fonts load

Script fonts are registered when the engine starts, from metadata computed at build time (family, style, which
characters each face covers), but without their bytes. Typst picks fonts as usual, by family or by falling back to the
first font that covers the text, so it chooses a script font exactly as if it were loaded. Then:

1. The compile notes that it wanted a font it has no bytes for, and carries on: for now the text falls back to the
   next font or shows as boxes. The compile itself succeeds.
2. The engine's worker fetches the font. Fetched fonts are kept in Cache Storage (`typstream-fonts`), so each
   downloads once per browser.
3. Once the font has arrived, the engine compiles the document again on its own, and the text appears in the right
   font. You don't need to do anything.

Exports wait for missing fonts too: an export whose compile lacked a font waits up to 3 seconds for it, then compiles
again with it, or exports without it if it doesn't arrive in time.

## Fonts in the HTML target

In the HTML target the browser draws the text, with the reader's fonts and your CSS. Typst's HTML export leaves fonts
out: `#set text(font: "…")` changes nothing there. The engine's fonts matter only where Typst draws something itself,
such as the drawings `@typstream/html-compat` turns into inline SVG (CeTZ canvases, polygons). For Arabic or Bengali in
the HTML target, the reader's system fonts are used unless your page loads web fonts for those scripts. The families a
font catalogue loads are the exception: see [the next section](#any-google-fonts-family).

Math is the exception. Typst writes math as MathML, and browsers need a math font to stretch delimiters and set
math italics. `@typstream/html-compat`'s stylesheet asks for New Computer Modern Math, and `typstream`'s
`<Typstream>` registers the engine's copy of it as a web font. With `@typstream/react`, pass its URL yourself:

```tsx
import { baseFonts } from "@typstream/engine-wasm/fonts";
import { Typstream } from "@typstream/react";

const mathFont = baseFonts.find((url) => url.pathname.includes("NewCMMath"));

<Typstream source={text} mathFont={mathFont} />;
```

Without React, `registerMathFont(url)` from `@typstream/dom` does the same. It uses the FontFace API, so it needs no
`font-src` exception for inline CSS.

## Any Google Fonts family

With the `@typstream/google-fonts` plugin, a document can name any family of the
[Google Fonts](https://fonts.google.com) library, and a model writing one can use whichever suits it:

```tsx
import { googleFonts } from "@typstream/google-fonts";
import { Typstream } from "typstream";

<Typstream source={text} plugins={[googleFonts]} />;
```

```typst
#set text(font: "Lora")
#show heading: set text(font: "Playfair Display")

= Fractions
#text(font: "Caveat")[Show your working.]
```

Pass the plugin to `buildSystemPrompt` from `@typstream/edu` too: its prompt rules tell the model it may use any Google
Fonts family by its exact name, and which families stand in for Arial, Times New Roman or Calibri, which aren't in the
library.

### How it works

The plugin gives the engine a **font catalogue**: an index of the library's 2,000 families and their font files
(`catalogue.json`, 465 KB, 67 KB gzipped), pinned to one commit of
[github.com/google/fonts](https://github.com/google/fonts), whose files [jsDelivr](https://www.jsdelivr.com) serves.

1. A document names a family the engine doesn't have. Typst warns `unknown font family: lora`, and the text falls
   back to the base fonts for now.
2. The worker looks the family up in the index (fetched the first time) and downloads its files. Fonts are the
   worker's, so every document has the family from then on.
3. The engine compiles the document again with it, as it does when a [lazy font](#how-lazy-fonts-load) arrives.
   Exports wait for it too.

**In the paged target** Typst draws the text with the family's files, as in the PDF. **In the HTML target**, the
plugin's preamble marks text in another font than the document's own with its family
(`<span data-typstream-font="lora">`; not inside equations, which keep their math font). When the engine has loaded a
family, `mountTypstream` (and so `<Typstream>`) registers the same files as web fonts and shows the marked text in it.
Text in a family that didn't load keeps your page's font. HTML exports (`exportHtml`) link the families they use.

### Limits

- **Size.** A family whose files add up to more than 5 MB isn't loaded: that leaves out most CJK families (10–20 MB).
  `createGoogleFonts({ maxBytes })` raises the limit. Families that are only one file per style (variable fonts, as
  most popular ones are) load whole. A static family larger than 1 MB loads only its regular and bold of each style,
  and Typst gives other weights the nearest of those.
- **Names.** A family must be named exactly as Google Fonts names it (`"Open Sans"`, not `"OpenSans"`), case aside.
  Arial, Helvetica or Calibri aren't in the library: the text keeps the base fonts, and a warning stays.
- **Network.** Readers' browsers download the index and the files from `cdn.jsdelivr.net`. Under a
  Content-Security-Policy, add it to `connect-src` ([Security](/docs/guides/security#content-security-policy)). To keep
  readers off third-party servers, mirror the files and point a copy of the index at your mirror:
  `createGoogleFonts({ index: "/fonts/catalogue.json" })`, whose `base` is your mirror's URL.
- **Node.** `@typstream/node`'s server loads nothing from catalogues.

### A catalogue of your own

Any plugin can bring a catalogue, in `engine.fontCatalogues`: `{ index, maxBytes? }`, where `index` is the URL of a
JSON file in this shape (`FontCatalogueIndex` in `@typstream/core`):

```json
{
  "version": 1,
  "base": "https://fonts.example.com/files/",
  "families": {
    "school sans": {
      "name": "School Sans",
      "files": [
        { "path": "SchoolSans[wght].ttf", "style": "normal", "weight": [300, 800], "bytes": 412000 },
        { "path": "SchoolSans-Italic[wght].ttf", "style": "italic", "weight": [300, 800], "bytes": 431000 }
      ]
    }
  }
}
```

Families are keyed by their name lowercased, which is how Typst compares names, and `name` must be the name in the
font files. Files are TTF or OTF (Typst reads no WOFF); `base` is relative to the index's URL. Unlike `engine.fonts`,
a catalogue works from a document's plugins too: it only names fonts, which the worker loads for itself when a document
asks for one. To show its families in the HTML target, add `googleFontsPreamble` from `@typstream/google-fonts` to your
plugin's preamble and allow the attribute it writes (`sanitize: { allowAttrs: { span: ["data-typstream-font"] } }`).

## Right-to-left text

Set the language, and Typst sets the direction: `#set text(lang: "ar")` for a whole document, `#text(lang: "ar")[…]`
for a passage. `@typstream/edu`'s templates take `lang: "ar"` and do this for you.

**Paged target.** Typst lays out right-to-left text itself. The selectable text layer over each page carries the
page's and each run's `lang` and `dir`, so selecting, copying and screen readers follow the text's direction.

**HTML target.** Typst's HTML export writes the document's language but no direction. The renderer adds it: it sets
`lang` and `dir` on its root element from the document's language, which orders lists and tables right to left.
Within the document, the theme gives paragraphs, list items, headings and table cells `unicode-bidi: plaintext`, so
each takes its direction from its first strong letter: an Arabic paragraph in an English document aligns right, and
the other way round. Standalone HTML exports get `dir="rtl"` on `<html>` the same way.

## Add your own fonts

CJK fonts aren't in the default set (one weight of Noto Serif SC is 11.6 MB), and you may want a brand font. Fonts
are given to the engine as `FontSource`s:

| Shape | Loaded |
|---|---|
| `{ kind: "url", url, info }` | Lazily: registered from `info`, fetched the first time a document uses it. |
| `{ kind: "url", url }` | When the engine starts. |
| `{ kind: "bytes", data }` | When the engine starts. |

`family` and `scripts` (ISO 15924 codes, such as `["Hani"]`) are informational. The URL is fetched by the engine's
worker, so give an absolute URL; under a strict Content-Security-Policy it must be allowed by `connect-src`.

<Callout type="warn" title="Beta">
  `FontSource`, the plugin facet `engine.fonts` and `createEngine`'s `initialize` are `@beta`.
</Callout>

### Compute `info`

`info` is the engine's metadata for the file: Typst's `FontInfo` for each face, as JSON. Compute it once, at build
time, with the version of `@typstream/engine-wasm` your app ships:

```js title="scripts/font-info.mjs"
import { readFileSync } from "node:fs";
import { createRequire } from "node:module";
import { Engine, initSync } from "@typstream/engine-wasm";

const require = createRequire(import.meta.url);
initSync({ module: readFileSync(require.resolve("@typstream/engine-wasm/engine_bg.wasm")) });

const info = Engine.font_info(readFileSync(process.argv[2]));
console.log(`export const info = ${JSON.stringify(info)};`);
```

```bash
node scripts/font-info.mjs public/fonts/NotoSerifSC-Regular.otf > src/noto-serif-sc-info.ts
```

### Give them to the engine

Fonts belong to the engine, not to a document: every document on an engine sees the same fonts. So create an engine
with them and hand it to your components:

```tsx title="app/preview-provider.tsx"
"use client";
import { type ReactNode, useEffect, useState } from "react";
import { createEngine, type Engine, engineWorker, TypstreamProvider } from "typstream";
import { info } from "../src/noto-serif-sc-info";

export function PreviewProvider({ children }: { children: ReactNode }) {
  const [engine, setEngine] = useState<Engine | null>(null);
  useEffect(() => {
    const created = createEngine({
      spawn: engineWorker(),
      initialize: {
        fonts: [
          {
            kind: "url",
            url: new URL("/fonts/NotoSerifSC-Regular.otf", location.origin).href,
            family: "Noto Serif SC",
            scripts: ["Hani"],
            info,
          },
        ],
      },
    });
    setEngine(created);
    return () => created.dispose();
  }, []);
  if (!engine) return null;
  return <TypstreamProvider engine={engine}>{children}</TypstreamProvider>;
}
```

The engine is created in an effect because it starts a Web Worker, which exists only in the browser. Every
`<Typstream>` under the provider uses it.

A plugin can carry fonts too, in `engine.fonts`. They load only when the plugin is passed to
`createEngine({ plugins })`. A plugin given only to a document (the `plugins` prop) can't add fonts to an engine that
is already running: the engine logs a warning (`plugin "…" brings fonts the engine doesn't have`) and the document
compiles without them.

## Fonts on the server

`@typstream/node` loads its fonts from disk when a worker starts. By default it has Typst's bundled set (Libertinus
Serif, New Computer Modern, DejaVu Sans Mono) and the three script fonts, all loaded up front. Add more with
`fontPaths` (directories searched recursively, like `typst --font-path`) or `fonts` (file bytes):

```ts
import { createEngine, render } from "@typstream/node";

const engine = createEngine({ fontPaths: ["/srv/fonts/noto-cjk"] });
const pdf = await render(source, "pdf", { engine });
```

`typstFonts: false` and `scriptFonts: false` leave out the default sets.
