Typst compilation strategies for large documents

[GiggleLiu]

Strategies for Fast Typst Compilation

Collected from Typst Forum and debugging slow compilation.

Diagnostics

1. Use --timings flag: typst compile --timings timings.json reductions.typ then load into Perfetto to identify bottlenecks
2. Use typst watch for incremental compilation (much faster than typst compile from scratch)
3. Compile locally — the CLI is faster than the web app

Document Structure

4. Split into chapter files: Use #import "template.typ": * per chapter, compile individual chapters during editing
5. Use external data files: Store data in JSON and load with json() rather than computing in Typst code. Already adopted in our paper via make examples
6. Avoid redundant imports: Use a central template file for shared definitions

Performance

7. Pre-generate figures separately: If graphics don't change, generate them independently and embed results (e.g., our approach: JSON data → cetz rendering)
8. Minimize heavy packages: cetz and fletcher are known slow packages. For simple tables/matrices, prefer native Typst table() and math.mat()
9. Batch compilation: Split multi-version projects into smaller chunks

Our Current Setup

• make examples generates JSON data files from Rust examples
• make paper depends on examples, then compiles the Typst document
• reductions.typ loads JSON with json() for data-driven content (example boxes, resource estimation table)
• Petersen graph visualization uses pre-computed JSON rather than Typst-side computation

References

• Best practices for working with longer documents - Typst Forum
• How can I figure out why my typst document is slow to compile? - Typst Forum
• Large compilation time with images - typst/typst#2096