typst-pack 0.4.0

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

typst-pack

GitHub Workflow Status OpenSSF Scorecard crates.io docs.rs

Portable single-file packs of Typst projects: sources, resources, packages, and fonts.

A pack (.typk) captures the compilation contract of one Typst project:

  • the packed 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.

Features

  • Portable project archives: bundle Typst sources, resources, packages, and fonts into one .typk file.
  • Structural project closure: include every eligible regular file beneath the selected project root, independently of compiler control flow.
  • Reproducible compilation: compile without network or system font access, with support for fixed timestamps and vendored packages.
  • Pack Overrides: replace any contained project file for one compilation without mutating the Pack.
  • Library and CLI interfaces: create, inspect, compile, and extract packs in memory or on the file system.

CLI

Install the command-line tool:

cargo install typst-pack-cli

# Pack a named source file, vendoring all observed packages:
typst-pack create path/to/project/main.typ

# 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

# Replace a contained placeholder for one compilation:
typst-pack compile invoice.typk customer.pdf --override assets/logo.png customer-logo.png

# 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 reproducible.pdf --creation-timestamp 1700000000

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

# Experimental HTML export (the output format enables its required feature):
typst-pack compile project.typk out.html

# An HTML representative creation compile still selects the feature explicitly:
typst-pack create project/main.typ --target html --features html

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

For Page Formats, {p} expands to the one-based Source Page Number, {0p} and {n} are zero-padded aliases, and {t} is the total source-document page count before page selection. Multi-page output requires an explicit {p}, {0p}, or {n} template. All target paths are checked for duplicates before writing. Document Format output paths are literal.

Project files

create stabilizes every eligible regular file beneath the physical project root before compiling. Project membership is independent of the representative compile's target, inputs, date, features, and control flow. The root .typkignore applies Gitignore-style ordered rules; it is always packed, nested .typkignore files are ordinary project files, and every .typk path is always excluded. Symlinks and other unignored non-regular entries are rejected.

Creation runs one representative compile from those stabilized bytes to select exact package and font dependencies. --target paged|html is optional and defaults to paged; it does not restrict later output formats. This concrete evaluation is a temporary dependency-selection mechanism because Typst does not report every package or font a different request might reach.

Every project path in a Pack has contained bytes. For per-document variation, pack a valid placeholder and use compile-time --override PACK_PATH FILE. Overrides may replace source, assets, data, or the entrypoint, but cannot add or delete paths or authorize undeclared packages and fonts.

Packages

All observed package dependencies are vendored into the pack by default. With --no-vendor-packages, each dependency is instead recorded as an exact package specification and Complete Package Tree identity. Compilation acquires the whole tree from the configured package directory, cache, or Typst Universe, verifies it before invoking Typst, and exposes only the verified paths and bytes. Undeclared package locations and ambient caches cannot satisfy imports.

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

Every selected face is recorded in the ordered Pack Font Catalog with its exact container identity. Fonts are not embedded by default: compilation must find the declared exact containers among the configured system, Typst-embedded, or --font-path sources. Other available fonts are not exposed to Typst.

With --embed-fonts, selected containers are stored in the pack, except those identical to Typst's embedded fonts. Pass --include-typst-embedded-fonts to store those too. Mind font licenses when redistributing embedded containers; licensing and acquisition metadata do not change font selection.

Output formats

PDF and HTML are Document Formats and produce one Compilation Output Artifact without a Source Page Number. PNG and SVG are Page Formats and produce one artifact per selected source page. Page artifacts retain their original Source Page Number and are emitted once each in source-document order.

HTML export is experimental in Typst itself, and Typst emits a warning that its behavior may change. Pack compilation derives the required engine feature from CompilationOutputSpecification::Html; HTML creation still requires --features html (or TYPST_FEATURES=html).

The Dagger compile function returns a directory for every format. Document Formats use output.pdf or output.html; Page Formats use deterministic names such as page-2.png, derived from Source Page Numbers. Its typed mapping, staging, failure boundary, and intentional transport omissions are documented in the Dagger adapter contract.

Maintainers changing the embedded compiler must follow the embedded Typst upgrade procedure. CI enforces the approved crate graph, classified differential matrix, official CLI oracle, and the packaged release binary.

Library

Add the crate with filesystem-backed packing support and Typst's embedded fonts:

[dependencies]
typst-pack = { version = "0.4", features = ["embedded-fonts", "fs"] }

The core in-memory packing and compilation APIs require no crate features.

use typst_pack::{
    compile, CompilationOutputSpecification, OutputFormat, Pack,
    PackCompilationRequest, Packer, PdfOutputSpecification,
};

// 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 request = PackCompilationRequest::new(
    pack,
    CompilationOutputSpecification::Pdf(PdfOutputSpecification::default()),
);
let report = compile(request)?;
let output = report.result().expect("semantic compilation result");
assert_eq!(output.engine_identity().implementation(), "typst");
assert_eq!(output.exporter_identity().implementation(), "typst-pdf");
let artifact = output.artifacts().first().expect("PDF artifact");
assert_eq!(artifact.format(), OutputFormat::Pdf);
assert_eq!(artifact.source_page_number(), None);
let pdf = artifact.bytes();

PackOutcome::warnings retains warnings from the representative creation compile. Inspect PackOutcome::pack for authoritative project files, package requirements and their embedding disposition, and the Pack Font Catalog; that static inventory is not duplicated in the creation outcome.

compile always returns a CompilationReport after accepting the semantic request. Its outcome contains either the immutable semantic result or an operational dependency failure, and its fulfillment report retains caller-supplied package and font provenance, cache disposition, and licensing metadata without including those operational values in Compilation Identity or Compilation Result Identity. Request rejection is the outer error and retains the complete request inventory. Every semantic result also exposes its document summary and canonical Compilation Access Trace.

For PNG and SVG, source_page_number() identifies each artifact independently of its collection position. bytes() borrows the artifact bytes and into_bytes() extracts them without cloning.

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()?;

Compilation-time Pack Overrides replace contained project-file bytes in memory:

let pack = Pack::builder("main.typ")
    .file("main.typ", source_text.as_bytes().to_vec())?
    .file("assets/logo.png", placeholder_png)?
    .build()?;
let overrides = PackOverrideSet::new(&pack)
    .replace("assets/logo.png", customer_png)?;
let request = PackCompilationRequest::new(
    pack,
    CompilationOutputSpecification::Pdf(PdfOutputSpecification::default()),
).overrides(overrides);
let report = compile(request)?;
let output = report.result().expect("semantic compilation result");

Compilation authority

The public compilation boundary accepts only a validated Pack bound into a PackCompilationRequest. The Pack-backed Typst World, compilation kernel, and embedded compiler and exporter adapter are private. In particular, callers cannot substitute a typst::World, language library, compiler, or exporter:

use typst_pack::PackWorld;

use typst_pack::compile_pack;

use typst_pack::compile;

fn arbitrary_world(world: &dyn typst::World) {
    let _ = compile(world);
}

Typst 0.15.0 owns language evaluation, layout, official diagnostics, document structures, and PDF, PNG, SVG, and HTML export behavior. typst-pack owns Pack creation and validity, the fixed set of contained project paths, exact package and font verification, Pack Overrides, request identities and reports, and later CLI or Dagger publication. Artifact bytes and official diagnostics are not reinterpreted by destination, transport, cache, or presentation code.

Intentional differences from typst compile are Pack confinement, Pack input instead of a source root, a fixed contained project namespace, exact dependency fulfillment, Pack Overrides, unsupported Bundle output, and publication rules for immutable artifacts. The complete version-bound inventory is in docs/cli-parity.md.

Migrating to 0.4

Version 0.4 makes clean naming and invariant-boundary breaks without retaining compatibility aliases:

  • Remove Resource Slot and Resource Provider APIs; pack valid baseline placeholders and replace contained files with Pack Overrides.
  • Rename Dagger arguments: source -> project, entrypoint -> input, inputs -> sysInputs, noPackages -> noVendorPackages, sourceDateEpoch -> creationTimestamp, and CreationTarget -> TypstTarget. Removed resource and inclusion arguments have no replacements.
  • Change creation from a directory plus --entrypoint/--output to create <INPUT> [OUTPUT].
  • Replace compile_pack(request) with compile(request). The provisional arbitrary-World compile overload and public PackWorld builder are removed; configure semantic values on PackCompilationRequest.
  • compile returns CompilationReport; inspect report.outcome() or report.result(). compile_report, PackCompileError, CompilationAttempt, and the empty CompilationExecutionControls are removed. Request rejection now owns its inventory and ordered CompilationRequestIssue values.
  • Replace CreationTarget and CompilationTarget with TypstTarget.
  • Configure document time with one DocumentTime value. Absent, Fixed, and UnixTimestamp replace the former date/timestamp fields and setters.
  • Read representative-compile warnings from PackOutcome::warnings; the one-field PackReport is removed.
  • Pack Manifest fields and PackFont fields are read-only. Use accessors such as manifest.project(), project.entrypoint(), font.manifest(), and font.data(). Package declarations are reached only through manifest.packages().vendored() and .unvendored().
  • Shared Pack consistency failures are available as PackInvariantError, wrapped by PackBuildError::Invariant or PackReadError::Invariant.
  • Replace OutputFormat plus CompileOptions request construction with the corresponding CompilationOutputSpecification variant and format-specific structure. PDF creation time is configured through PdfOutputSpecification::creation_timestamp; use CreationTimestamp::Omit to suppress PDF creation datetime metadata.
  • ExtractError adds PlannedPathConflict and DestinationConflict; exhaustive matches must handle both variants.

The unstable Pack format remains version 1, but discovery and Resource Slot fields are removed in place. Old fields and aliases are not accepted.

Feature flags

  • fs: Packer, extract, package download and caching, system font scanning. Requires a file system, so disable this for wasm targets.
  • embedded-fonts: make Typst's bundled fonts available as intentional creation and external-fulfillment sources.
  • diagnostics: retain source context for first-party diagnostic presentation adapters.
  • parallel: export independent page artifacts in parallel.

All library crate features are opt-in. Fixed timestamp conversion for DocumentTime is part of the featureless core and remains available on wasm targets.

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]]
spec = "@preview/cetz:0.3.4"
tree-digest = "0123456789abcdef0123456789abcdef"
tree-identity-kind = "complete-package-tree"
tree-identity-schema = "typst-pack-complete-package-tree-v1"
tree-identity-algorithm = "typst-hash128-0.15"
file-count = 12
byte-length = 34567

[[packages.unvendored]]
spec = "@preview/tablex:0.0.9"
tree-digest = "fedcba9876543210fedcba9876543210"
tree-identity-kind = "complete-package-tree"
tree-identity-schema = "typst-pack-complete-package-tree-v1"
tree-identity-algorithm = "typst-hash128-0.15"
file-count = 8
byte-length = 23456

[[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 whose format-version is not the exact supported version. Paths inside the archive are validated, root-relative virtual paths. Extraction rejects existing symlinked entries within the selected destination before writing.

The format version remains 1 and is explicitly unstable: readers reject old discovery, Resource Slot, external-resources, and packages.external fields rather than retaining aliases.

Development

Minimum verification:

  • cargo fmt --all -- --check
  • cargo clippy --workspace --all-targets --all-features -- -D warnings
  • cargo test --workspace --all-features

Run CI's containerized checks with Dagger:

  • dagger check

The containerized suite includes the embedded Typst CLI differential gate, pinned to the exact official release used by the library.

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.