Crate typst_pack

Expand description

§typst-pack

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

Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

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.

Modules§

cli: The typst-pack command line interface.

Structs§

CompileOptions: Options for compile.
CompileOutput: The result of compiling a pack.
DiscoveryWorld: The file-system-backed world used for the discovery compile.
ExtractOptions: Options for extract.
ExtractReport: A summary of an extraction.
FontManifest: One [[fonts]] entry.
Manifest: The parsed contents of typst-pack.toml.
Metadata: The optional [metadata] section.
OfflineDownloader: A package downloader that refuses to download.
Pack: A portable pack of a Typst project.
PackBuilder: Builds a Pack from in-memory data.
PackFont: A font embedded in a pack.
PackOutcome: The result of a successful Packer::pack run.
PackReport: A summary of what a Packer put into a pack.
PackWorld: A complete Typst World that serves all resources from a Pack.
PackWorldBuilder: Configures a PackWorld.
PackagesManifest: The [packages] section.
Packer: Packs a Typst project directory into a Pack.
ProjectManifest: The [project] section.
SystemPackageLoader: A FileLoader that resolves package files from standard system locations (and Typst Universe), for compiling packs whose dependencies are not vendored. Project file requests always fail: those must come from the pack.

Enums§

CompileError: A failed compilation.
ExtractError: A failure while extracting a pack.
ManifestError: A manifest that could not be accepted.
OutputFormat: The output formats a pack can be compiled to.
PackBuildError: A failure while building a pack in memory.
PackReadError: A failure while reading a pack archive.
PackWorldError: A failure while building a PackWorld.
PackWriteError: A failure while writing a pack archive.
PackerError: A failure while packing a project directory.

Constants§

FILE_EXTENSION: The conventional file extension for packs.
FORMAT_VERSION: The pack format version this crate reads and writes.
MANIFEST_PATH: The archive entry name of the manifest.

Functions§

compile: Compiles the world’s document and exports it in the requested format.
extract: Writes the project files of a pack into a directory.
parse_pages: Parses a --pages-style page selection like 1,3-5,9-.

Type Aliases§

PageRange: A one-indexed, inclusive page range with optional open ends.

Crate typst_pack

Crate typst_pack Copy item path

§typst-pack

§CLI

§How files are discovered

§Packages

§Fonts

§Output formats

§Library

§Feature flags

§Pack format

§License

§Contribution

Modules§

Structs§

Enums§

Constants§

Functions§

Type Aliases§

Crate typst_pack