typst-nix -- typst compilation in a nix derivation

Before you use this flake, please go check out Typix -- a more mature project that does basically the same thing. I am building this package, because I believe Typix to be not abstract enough, while lacking the ability to automatically resolve all the dependencies.

How to use

1. Add to your flake inputs:

inputs.typst-nix.url = "https://git.dzuchun.ing/dzu/typst-nix.git";

2. Run typst-lock against your typst document.

This flake exposes it at apps.<system>.default, or you may do

cargo install --git https://git.dzuchun.ing/dzu/typst-nix.git

Help text:

Statically resolve and lock `@preview` packages for a Typst project

Usage: typst-lock [OPTIONS] [ENTRYPOINT]

Arguments:
  [ENTRYPOINT]
          `.typ` file to start with, relative to `<ROOT>`

          Defaults to `main.typ`

Options:
      --root <ROOT>
          Project root

          Defaults to CWD

      --lockfile <LOCKFILE>
          Path of the lockfile to write.

          Defaults to `<ROOT>/typst.lock`

      --force
          Even if the lockfile is present at the output location, ignore it and resolve everything from scratch

      --prefetch-url-path <PREFETCH_URL_PATH>
          Path to the `nix-prefetch-url` binary

          Defaults to whatever is first in `PATH`

  -h, --help
          Print help (see a summary with '-h')

  -V, --version
          Print version

This tool produces a special file at typst.lock (or whatever you pass into --lockfile), that you can commit -- this is a direct Typst equivalent to flake.lock and Cargo.lock.

3. Call into the nix function.

The main function is located at .lib.compileTypst. You may use aliases at .lib.<system>.compileTypst, if you don't care where pkgs come from.

Signature:

compileTypst :: {
    pkgs,
    # package to take the typst binary from
    typstPackage ? pkgs.typst,
    # possible values: pdf, png, svg, html, bundle
    format ? "pdf",
    # root of the typst project
    rootDir,
    # main typst file
    entrypoint ? "${rootDir}/main.typ",
    # lockfile, representing the dependencies
    lockfile ? "${rootDir}/typst.lock",
    # exposed in Typst as `sys.inputs`. must be an attrset of strings
    inputs ? { },
    # exposed in Typst as `sys.inputs`. must be an attrset of paths
    inputFiles ? { },
    # paths to fonts
    fontPaths ? [ ],
    # if set, Typst's own embedded fonts will be ignored
    ignoreEmbeddedFonts ? false,
    # UNIX timestamp exposed by datetime functions
    creationTimestamp ? 0,
    # pretty-format the output
    pretty ? false,
    pages ? null,
    # see typst c --help
    noPdfTags ? false,
    # see typst c --help
    ppi ? 144,
    features ? [ ],
    ...
} -> Derivation

Output of the produced derivation is your PDF or HTML respectively.

Known limitations

• First version only supports packages from typst universe. There is a code in place to support custom (incl. local) repositories, but this is deferred.
• Tool operates on the "fail open" strategy: non-existent or unresolvable packages are skipped with a warning, while errors in your entrypoint are fatal.
• If the package traversal fails in any way, it will remain in the manifest, but without its dependencies. You will also see an explicit message about this hard failure.
• Tool only understands imports and includes with literal string sources. This may or may not be relaxed to "pure+local eval values" in the future.
• All the resolutions and downloads are naive and never retried. If one of the packages you are sure to exist fails, please rerun.
• Power loss durability is not a goal. If you think that the lockfile is corrupted, just regenerate it.