# Typst projects

Pin a Typst version per project, add packages from Typst Universe, control fonts, build variants and reproducible PDFs, and convert a LaTeX project to Typst.

Oleafly comes with Typst 0.15.1 and the Tinymist 0.15.8 language server, so a new Typst project compiles with nothing to install. This page covers what you can change: which Typst a project uses, where its packages and fonts come from, and how a single source builds more than one PDF. For syntax and the toolbar, start with [Write in Typst](/docs/writing/typst/).

## Typst versions

Open **Settings → Engines → Typst**. The first card is **Typst (built in)**, the version that ships with the app. If a `typst` is already installed on your computer, on your `PATH`, in Homebrew's folder or in `~/.cargo/bin`, a second card shows it as **Typst on this computer**. Projects that pin that exact version can compile with it.

Below them, **Versions** lists Typst 0.11 to 0.15, newest first. Each row gives the release date, the download size, where the copy comes from (**Built in**, **Downloaded** or **System**) and, once installed, the Tinymist release it uses.

- **Install** downloads that version. Oleafly tries its own mirror first and GitHub second, and checks the archive and the program inside it against SHA-256 checksums built into the app. A file that doesn't match is thrown away, and a failed or cancelled install leaves nothing behind. Downloads live in `~/.oleafly/toolchains/typst/`.
- The round button at the left of an installed row makes that version the default.
- **Remove** deletes a downloaded version. The default can't be removed, so pick another default first.

### The default version and project pins

New Typst projects pin the default version. So do projects made from a template, imported projects and linked folders. A pin is stored in the project's `project.json` as a version number, not a path, so it still works after you move the project or open it on another computer.

Changing the default later doesn't move existing projects. That is deliberate: a pinned paper keeps the same line breaks and page count when Oleafly ships a newer Typst.

To change one project's version, open the arrow beside **Recompile** and look under **Typst version (this project)**. **Default** follows the version chosen in Settings and clears the pin. The other entries are the versions installed on this computer, marked **[built in]** or **[system]** where that applies. To use a version that isn't listed, install it in Settings first.

### When a pinned version is missing

If you open a project that pins a version this computer doesn't have, Oleafly won't quietly build it with a different Typst. The compile stops with "Typst 0.13.1 is not installed", and the preview offers two buttons:

- **Download Typst 0.13.1** installs the pinned version and compiles again. It appears when the version is one Oleafly offers.
- **Use Typst 0.15.1**, named after your default version, clears the pin and compiles again with the default.

The compile menu marks the pin **[not installed]** until you choose one of them.

### Try a newer version before switching

With a Typst project open, the Typst tab in Settings shows **Try a newer version** whenever a newer Typst is installed. Choose **Check with Typst 0.15.1** (or whichever version it names). Oleafly builds the project twice in temporary folders, once with the project's current version and once with the newer one. Nothing in your project changes.

The report shows whether each build succeeded, its page count, and its errors and warnings. It tells you if the page count changes. **New in Typst 0.15.1** lists messages that only the newer version reports, and **No longer reported by Typst 0.15.1** lists the ones that go away. Click a message to open its file at that line.

If you like what you see, **Switch to Typst 0.15.1** pins the project to the newer version. **Check again** reruns both builds after you fix something.

### The language server follows the version

Tinymist powers completion, hover help, rename and formatting in Typst files (see [Code intelligence](/docs/code-intelligence/#typst-files)). Each Typst minor version has its own Tinymist release, and a project talks to the one that matches its Typst version.

The built-in Tinymist covers Typst 0.15. When you open a project pinned to an older line, Oleafly downloads the matching Tinymist in the background, with the same checksum check, and the status reads "Downloading Tinymist 0.13.30 to match this project's Typst version." If the download fails, Oleafly tries again later. When Settings finds Tinymist downloads that no installed Typst needs any more, it offers **Remove unused language server downloads**.

### What each version can do

Older versions exist so that projects started on them keep building the same way. Some features depend on what the Typst version itself supports:

| Feature | 0.11 | 0.12 | 0.13 | 0.14 and later |
| --- | --- | --- | --- | --- |
| Project fonts only | No | Yes | Yes | Yes |
| Reproducible build | No | Yes | Yes | Yes |
| Page ranges in PNG and SVG export | No | Yes | Yes | Yes |
| PDF/A | No | PDF/A-2b | PDF/A-2b, PDF/A-3b | All PDF/A levels Typst offers |
| PDF/UA-1 | No | No | No | Yes |
| HTML export, and Word or Markdown export through Typst's HTML | No | No | Yes | Yes |
| [Source and PDF sync](/docs/synctex/) | No | No | Yes | Yes |
| Tagged PDF on every compile | No | No | No | Yes |

The font picker can say where each font comes from on Typst 0.15 and later. When a setting can't apply to the version a project uses, the compile menu marks it **Needs a newer Typst**.

## Packages from Typst Universe

Choose **Typst packages**, the package icon at the right end of the Typst toolbar. Search Typst Universe by name, keyword or category. Each package shows its latest version, and a package that needs a newer Typst than the project uses says so: "Needs Typst 0.14.0. This project uses Typst 0.13.1."

**Insert import** writes the `#import` line at the top of the open Typst file. **Copy import** puts it on the clipboard instead.

Typst downloads a `@preview` package the first time a compile imports it and keeps it in a cache that every project shares. The package list is cached too. Offline, the dialog shows the last list it fetched, with its date.

### Newer releases

When an import names an older release than the one on Typst Universe, its version number is underlined with a hint such as "cetz 0.4.2 is available. This import uses 0.3.4." The hint card offers **Update to 0.4.2**, which changes the version number in the import. Read the package's changelog before you accept it, because a new release can change how the package is called. Hovering over an import also offers **Open on Typst Universe**.

### Keep packages inside the project

Under **Project packages** in the same dialog, **Vendor packages into project** copies every package the project imports into a `typst-packages` folder at the top of the project. It also copies the packages those packages import, and turns on **Use packages from the project folder**.

From then on Typst looks in `typst-packages` first. A vendored project compiles offline and on any computer, and the folder can go into Git with your source. A package you haven't vendored still comes from the shared cache.

If a package isn't in the cache yet, the dialog names it: "These packages aren't in the package cache: …". Compile once while online, then vendor again.

### Offline mode

With **Offline mode** on in **Settings → General**, Typst can't download anything. Every package has to be in the shared cache or in `typst-packages` already. If one isn't, the compile fails and the message names the package, so you know what to fetch the next time you're online.

## Fonts

Typst finds fonts in three places: the fonts built into Typst, the fonts installed on your computer, and font folders inside the project. Put font files in a folder named `fonts` at the top of the project, and both the compiler and the language server pick them up. Extra folders can be listed under `typst.font_paths` in `project.json`. Folders outside the project are ignored.

Under **Fonts (this project)** in the compile menu, **Use system fonts** is the default. **Project fonts only** stops Typst from reading the fonts installed on this computer. The PDF then comes out the same on every machine, and if the document asks for a font the project doesn't include, you find out on your own computer instead of a co-author's.

To choose a body font, open **Document settings**, the sliders icon on the Typst toolbar, and click **Body font**. The list shows every family Typst can find with the project's current font settings. On Typst 0.15 and later each family carries a **Project**, **System** or **Built in** label. Pick one and choose **Apply**, and Oleafly writes it into the document's `#set` rules.

## Build variants and sys.inputs

A build variant is a named set of values your document reads through `sys.inputs`. Use variants when one source needs to produce different PDFs, such as an anonymous review copy and a camera-ready copy, or a draft with a watermark.

The document decides what each value does. Values always arrive as text:

```typst
#let draft = sys.inputs.at("draft", default: "false") == "true"

#if draft [*Draft. Do not circulate.*]
```

To set up a variant:

1. Open **Document settings** and scroll to **Build variants**.
2. Choose **Add variant** and name it, for example `review`.
3. Choose **Add value**, then enter `draft` under **Name** and `true` under **Value**.
4. Choose **Apply**.
5. Open the compile menu. **Variant (this project)** now lists `review`. Pick it and compile.

**No variant** builds without any variant values. The variant you pick is remembered on this computer only, so a co-author can build a different one from the same project. The variants themselves are saved in `project.json`. Exports use the selected variant too.

Values that every build should get go under `typst.inputs` in `project.json`. When a variant sets a value with the same name, the variant wins.

## Reproducible builds

Under **Build (this project)** in the compile menu, **Reproducible build** makes the same sources give the same PDF on any computer. It uses only project fonts and Typst's built-in fonts, and it dates the PDF to the last Git commit. A project that isn't a Git repository gets a fixed date of 1 January 1970.

This matters when a PDF has to match a checksum, for an archive deposit or a comparison in CI. It needs Typst 0.12 or later. While it's on, **Use system fonts** is unavailable. **Standard build** is the default.

## Live preview with Auto compile

Set **Auto compile** to **On** in the compile menu. In a Typst project, Oleafly then keeps one Typst process running. The open file saves itself a moment after you stop typing, Typst compiles it, and the preview reloads at the same scroll position. There is no separate live preview setting: Auto compile is the live preview.

While Typst starts, the menu shows "Starting Typst". If it stops after repeated errors, the menu says so, and your next edit starts it again. **Stop compilation** ends the process, and the next edit starts it again too. LaTeX and Markdown projects handle Auto compile differently; see [Compiling](/docs/compiling/#auto-compile).

## Build from the command line

`oleaflyc`, Oleafly's command-line tool, builds projects without opening the app. For now it's built from the desktop source code and doesn't ship with the app.

For a Typst project, `oleaflyc build` and `oleaflyc watch` read `project.json` and use the same settings as the app: the pinned version, vendored packages, font folders, the system fonts switch, inputs and reproducible builds.

- `--variant review` builds a variant. A name the project doesn't define stops the build, and the message lists the variants it does have.
- `--offline` blocks package downloads, like Offline mode in the app.
- A pinned project builds only with that exact Typst. The CLI looks at `OLEAFLY_TYPST`, then the versions the app downloaded, then the `typst` beside the CLI, then your `PATH`. If none reports the pinned version, the build stops before Typst runs and tells you how to install it.
- A project without a pin uses `OLEAFLY_TYPST`, the bundled Typst or the one on your `PATH`, in that order. It doesn't read the default version from Settings.
- `oleaflyc doctor` lists every Typst it found and the settings a build would use. It fails when the pinned version is missing.

If a setting can't apply to the Typst being used, the build prints a note, for example that Typst 0.11.1 can't ignore system fonts. Errors in the terminal include Typst's own hints.

## Convert a LaTeX project to Typst

Open the LaTeX project, press ⌘K (Ctrl+K) and run **Convert to a Typst project**. Give the new project a name and choose **Convert**. The LaTeX project stays exactly as it was. Oleafly builds a separate Typst project from it:

- Pandoc converts the text, math, figures and tables. If Pandoc isn't set up yet, Oleafly sets it up first.
- Each file brought in with `\input`, `\include` or `\subfile` becomes its own `.typ` file.
- BibTeX files are copied unchanged.
- Typst compiles the new project to check it.

The report then says whether the project compiles and counts what was converted: source files, figures, tables, display equations, cross-references, formulas the math converter repaired, and copied files, along with the bibliography style it chose. **Needs attention** lists what to fix by hand, such as a missing include or image, an image format Typst can't show, math the converter couldn't handle, a BibTeX style with no Typst match, or a label on one line of a multi-line equation, which now points at the whole equation. Compile errors and warnings link to their file and line.

Choose **Open the Typst project** to switch to it. The new project pins your default Typst version. While Oleafly stays open, **Show the Typst conversion report** in the command palette brings the report back.

To convert a single file instead of a whole project, use [LaTeX to Typst](/docs/tools/latex-to-typst/) on the Tools page.

## Related pages

- [Write in Typst](/docs/writing/typst/) for the toolbar and a first document.
- [Compiling](/docs/compiling/) for logs, the compile menu and offline mode.
- [Export and convert a project](/docs/export/#typst-images-and-html) for PNG, SVG, HTML, PDF/A and PDF/UA.
- [Preflight checks](/docs/preflight/#typst-projects) for the checks that read Typst sources.