typdeps

typdeps is a small wrapper that lets Typst projects import third-party packages with #import "@ns/name" (no version in source files). It resolves dependencies from typst.toml, pins them in typst.lock, rewrites imports into a temporary workspace, and then runs the real typst compile.

Requirements

• Rust (to build the tool)
• git (to fetch git dependencies)
• typst CLI on PATH (invoked by typdeps run)

Install / Build

cargo build
# or install locally
cargo install --path .

Quickstart

# in your Typst project directory
typdeps init
typdeps add gh:owner/repo?ref=main&subdir=.
typdeps run -- typst compile main.typ

# strict/CI mode (refuse lock updates)
typdeps sync
typdeps run --locked -- typst compile main.typ

Key behavior

• Dependencies come only from typst.toml [dependencies] (git only; no path deps).
• Only string-literal #import "@ns/name" is rewritten.
  • Versioned imports like @foo/bar:1.2.3 are not rewritten.
  • Non-literal import expressions are hard errors with file:line:col.
• typdeps run compiles from a temp workspace, but keeps paths stable:
  • Relative outputs are written back under the real project directory.
  • If [output] is omitted and <input> != "-", typdeps injects the default output path (next to the input; extension follows --format / -f, default pdf).

typst.toml format (dependencies)

[dependencies]
"@foo/bar" = { git = "https://github.com/example-user/example-package", ref = "main", subdir = "." }

Rules:

• Keys are always @ns/name (no version in the key).
• Only git dependencies are supported.
• ref is optional and may be a branch, tag, or commit (it is passed to git checkout).
• subdir is optional and defaults to ".".

Common errors

• typst.toml missing but third-party imports found: add typst.toml or remove @ns/name imports.
• typst.lock missing; run typdeps sync: run typdeps sync, or run without --locked once.
• typst.lock is stale (manifest-hash mismatch): run typdeps sync.
• unsupported import expression: only string-literal #import "@ns/name" is supported.
• missing [package].entrypoint: dependency package must define entrypoint in its typst.toml.

Further reading

• docs/overview.md: project purpose, constraints, and module map
• docs/cli.md: CLI contract
• docs/workspace.md: workspace layout and path transparency
• docs/resolution.md: dependency resolution
• docs/lockfile.md: typst.lock format and determinism
• docs/cache-git.md: git cache layout and hashing
• docs/errors.md: strict error semantics
• docs/development.md: testing and development notes