typst-pack 0.1.0

Portable single-file packs of Typst projects: sources, assets, packages, and fonts
Documentation

typst-pack

GitHub Workflow Status OpenSSF Scorecard crates.io docs.rs

Portable single-file packs of Typst projects.

A pack (.typk) contains everything needed to compile one Typst project:

  • the project files: the entrypoint, other Typst sources, images, and data files,
  • optionally the files of the Typst Universe packages the project imports, so compiling needs no network access,
  • optionally the fonts the document uses, so compiling produces identical output on machines without those fonts.

Use it as a CLI to distribute finished Typst projects, or as a library to produce and consume packs programmatically (e.g. offering a "download project" pack in a web-based Typst editor).

Note: this is unrelated to Typst's own bundle export (the typst-bundle crate), which is a multi-file output target. A pack is an input archive: a portable form of a project's sources and resources.

CLI

# Pack a project directory (entrypoint main.typ), vendoring all packages:
typst-pack create path/to/project

# Pack a specific entrypoint, embedding the fonts the document uses:
typst-pack create letter.typ --embed-fonts

# See what a pack contains:
typst-pack inspect project.typk

# Compile a pack without network access:
typst-pack compile project.typk output.pdf

# PNG or SVG output, page selection, reproducible builds:
typst-pack compile project.typk "page-{0p}.png" --ppi 300 --pages 1-3
typst-pack compile project.typk --creation-timestamp 1700000000

# Guarantee no network access (fails instead of downloading packages):
typst-pack compile project.typk --offline

# Experimental HTML export, gated like in the Typst CLI:
typst-pack compile project.typk out.html --features html

# Unpack a pack back into an editable project directory:
typst-pack extract project.typk -o project/

How files are discovered

create runs a discovery compile of the project and records every file Typst actually reads, the same mechanism typst compile --make-deps uses. Sources, images, data files, and package files are picked up automatically, including files accessed dynamically. Because discovery observes one concrete compile, files that would only be read under different --input values or on a different date are not seen; add those with --include <path> (a file or directory inside the project root).

A typst.toml next to the entrypoint (Typst's own package/template manifest, not to be confused with the pack's typst-pack.toml) is always packed as a regular project file, even though compiles don't read it. That way template and package metadata survives the round trip through create and extract.

Packages

All observed package dependencies are vendored into the pack by default. With --no-packages, they are instead recorded as external dependencies in the manifest; compiling such a pack resolves them from the local package directories or downloads them from Typst Universe, like the Typst CLI would.

--offline (on both create and compile) disables the download step entirely: dependencies must come from the pack or the local package directories, and anything else fails as not found. Use typst-pack compile --offline to verify that a pack is truly self-contained.

Fonts

Fonts are not embedded by default. With --embed-fonts, the fonts used by the rendered document are stored in the pack, except fonts identical to Typst's embedded defaults (Libertinus Serif, New Computer Modern, Deja Vu Sans Mono), which every consumer of this crate already has; pass --include-default-fonts to store those too. Mind font licenses when redistributing packs with embedded fonts.

When compiling a pack, fonts are used in this order of preference: --font-path fonts, pack fonts, embedded default fonts, and system fonts (disable the latter with --ignore-system-fonts).

Output formats

compile produces PDF (default), PNG, and SVG. HTML export is also supported but experimental in Typst itself; like the Typst CLI, it must be enabled explicitly with --features html (or TYPST_FEATURES=html), and Typst emits a warning that its behavior may change. In the library, enable it with PackWorldBuilder::feature(typst::Feature::Html) and compile with OutputFormat::Html.

Library

use typst_pack::{compile, CompileOptions, OutputFormat, Pack, PackWorld, Packer};

// Pack a project directory (requires the `fs` feature).
let outcome = Packer::new("path/to/project", "main.typ")
    .embed_fonts(true)
    .pack()?;
let bytes = outcome.pack.to_bytes()?;

// ... ship the bytes somewhere, then compile without a file system:
let pack = Pack::from_bytes(bytes)?;
let world = PackWorld::builder(pack).build()?;
let pdf = compile(&world, OutputFormat::Pdf, &CompileOptions::default())?
    .outputs
    .remove(0);

Packs can also be assembled fully in memory, with no file system involved, which is what a web editor wants:

use typst_pack::Pack;

let pack = Pack::builder("main.typ")
    .file("main.typ", source_text.as_bytes().to_vec())?
    .file("figure.png", image_bytes)?
    .build()?;
let bytes = pack.to_bytes()?;

Feature flags

  • fs (default): [Packer], [extract], package download and caching, system font scanning. Requires a file system, so disable this (and cli) for wasm targets.
  • cli (default): the typst-pack binary.
  • embedded-fonts (default): compile packs against Typst's default fonts.

Pack format

A pack is a Zip archive (Deflate), conventionally named *.typk, with this layout:

typst-pack.toml                     manifest (always first)
project/<path>                      project files, root-relative
packages/<ns>/<name>/<version>/<path>   vendored package files
fonts/<file>                        embedded font files

The manifest looks like this:

format-version = 1

[project]
entrypoint = "main.typ"

[packages]
vendored = ["@preview/cetz:0.3.4"]
external = ["@preview/tablex:0.0.9"]

[[fonts]]
path = "fonts/ibm-plex-sans.ttf"
families = ["IBM Plex Sans"]

[metadata]
name = "Quarterly report"
authors = ["Jane Doe"]

Readers ignore unknown top-level archive entries and reject manifests with a format-version greater than they support. Paths inside the archive are validated, root-relative virtual paths, so a pack can never read or write outside its own tree.

License

Licensed under either of

at your option.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.