Using Typst packages

TL;DR: Use this example as a template:
nix flake init --refresh -t 'github:loqusion/typix#with-typst-packages'

Typst packages are considered experimental at the time of writing, and the methods documented here may become outdated at any point if breaking changes are made upstream.

If you experience any unexpected errors or bugs, and there are no open issues related to your problem, feel free to open an issue.

There are two types of Typst packages: published and unpublished:

Published packages are those submitted to the Typst Packages repository and can be browsed on Typst Universe.
Unpublished packages are packages that are only available from unofficial sources. They can be stored locally on your system, on a GitHub repository, or elsewhere. ("Unpublished" can also refer to unpublished versions of a package which has published versions.)

Transitive dependencies — that is, a dependency's dependencies — must be added explicitly, in addition to any direct dependencies you have. For instance, cetz 0.3.4 depends on oxifmt 0.2.1, so if you use cetz 0.3.4 you must also ensure oxifmt 0.2.1 is provided. This applies recursively: if you depend on A which depends on B and B depends on C, you must explicitly specify both B and C, in addition to A. Also, the precise version is important: if different versions of the same package are imported, both versions must be specified.

The method to add Typst packages differs depending on whether they are published or unpublished.

Published Typst packages

Published Typst packages work out of the box for for watchTypstProject and commands executed while devShell is active.

For buildTypstProject, buildTypstProjectLocal, and mkTypstDerivation, there are two methods:

unstable_typstPackages (recommended)
TYPST_PACKAGE_CACHE_PATH

It is recommended to use unstable_typstPackages, as it is faster and consumes less disk space.

The `unstable_typstPackages` attribute

The unstable_typstPackages attribute is used to fetch packages from the official Typst packages CDN at https://packages.typst.org.

For more information, see the respective documentation for the attribute on buildTypstProject, buildTypstProjectLocal, and mkTypstDerivation.

{
  outputs = {
    nixpkgs,
    typix,
  }: let
    inherit (nixpkgs) lib;
    system = "x86_64-linux";

    unstable_typstPackages = [
      {
        name = "cetz";
        version = "0.3.4";
        hash = "sha256-5w3UYRUSdi4hCvAjrp9HslzrUw7BhgDdeCiDRHGvqd4=";
      }
      # Transitive dependencies must be manually specified
      # `oxifmt` is required by `cetz`
      {
        name = "oxifmt";
        version = "0.2.1";
        hash = "sha256-8PNPa9TGFybMZ1uuJwb5ET0WGIInmIgg8h24BmdfxlU=";
      }
    ];

    build-drv = typix.lib.${system}.buildTypstProject {
      inherit unstable_typstPackages;
      # ...
    };

    build-script = typix.lib.${system}.buildTypstProjectLocal {
      inherit unstable_typstPackages;
      # ...
    };
  in {
    packages.${system}.default = build-drv;
    apps.${system}.default = {
      type = "app";
      program = lib.getExe build-script;
    };
  };
}

The `TYPST_PACKAGE_CACHE_PATH` environment variable

This method downloads the entire contents of the Typst Packages repository, making all packages available in your Typst project.

First, add the repository to flake inputs:

{
  inputs.typst-packages = {
    url = "github:typst/packages";
    flake = false;
  };
}

Then, use it in flake outputs:

{
  outputs = {
    nixpkgs,
    typix,
    typst-packages,
  }: let
    inherit (nixpkgs) lib;
    system = "x86_64-linux";

    build-drv = typix.lib.${system}.buildTypstProject {
      TYPST_PACKAGE_CACHE_PATH = "${typst-packages}/packages";
      # ...
    };

    build-script = typix.lib.${system}.buildTypstProjectLocal {
      TYPST_PACKAGE_CACHE_PATH = "${typst-packages}/packages";
      # ...
    };
  in {
    packages.${system}.default = build-drv;
    apps.${system}.default = {
      type = "app";
      program = lib.getExe build-script;
    };
  };
}

Unpublished Typst packages

If the Typst package you want to use is stored locally — in the same repository as your flake — all you have to do is directly import the entrypoint module:

#import "my-typst-package/src/lib.typ": my-item

#my-item

You may want to expand the source tree or filter certain files.

If the imported module imports any packages, those packages must be specified using one of the methods documented in this chapter.

If you need to fetch an unpublished Typst package from a GitHub repository instead, see below.

Fetching from a GitHub repository

You can use this example as a template:

nix flake init --refresh -t 'github:loqusion/typix#with-typst-packages-unpublished'

Add the GitHub repository containing the unpublished Typst package to flake inputs:

{
  inputs = {
    my-typst-package = {
      url = "github:loqusion/my-typst-package";
      flake = false;
    };
  };
}

Then, create a derivation containing the inputs and pass it to Typst with the TYPST_PACKAGE_PATH environment variable:

{
  outputs = {
    nixpkgs,
    typix,
    my-typst-package,
  }: let
    system = "x86_64-linux";
    pkgs = nixpkgs.legacyPackages.${system};
    inherit (pkgs) lib;
    inherit (lib.strings) escapeShellArg;

    mkTypstPackagesDrv = name: entries: let
      linkFarmEntries =
        lib.foldl (set: {
          name,
          version,
          namespace,
          input,
        }:
          set
          // {
            "${namespace}/${name}/${version}" = input;
          })
        {}
        entries;
    in
      pkgs.linkFarm name linkFarmEntries;

    unpublishedTypstPackages = mkTypstPackagesDrv "unpublished-typst-packages" [
      # Unpublished packages can be added here
      {
        name = "my-typst-package";
        version = "0.1.0";
        namespace = "local";
        input = my-typst-package;
      }
    ];

    # Any transitive dependencies on published packages must be added here
    unstable_typstPackages = [
      {
        name = "oxifmt";
        version = "0.2.1";
        hash = "sha256-8PNPa9TGFybMZ1uuJwb5ET0WGIInmIgg8h24BmdfxlU=";
      }
    ];

    build-drv = typix.lib.${system}.buildTypstProject {
      inherit unstable_typstPackages;
      TYPST_PACKAGE_PATH = unpublishedTypstPackages;
      # ...
    };

    build-script = typix.lib.${system}.buildTypstProjectLocal {
      inherit unstable_typstPackages;
      TYPST_PACKAGE_PATH = unpublishedTypstPackages;
      # ...
    };

    watch-script = typix.lib.${system}.watchTypstProject {
      # `watchTypstProject` can already access published packages, so
      # `unstable_typstPackages` is not needed here
      typstWatchCommand = "TYPST_PACKAGE_PATH=${escapeShellArg unpublishedTypstPackages} typst watch";
      # ...
    };
  in {
    packages.${system}.default = build-drv;
    apps.${system}.default = {
      type = "app";
      program = lib.getExe build-script;
    };
    apps.${system}.watch = {
      type = "app";
      program = lib.getExe watch-script;
    };
  };
}

Finally, you can use the package in a Typst file:

#import "@local/my-typst-package:0.1.0": *

#nothing

Typix