GitHub - typst-community/setup-typst: 📑 Install Typst and add it to the PATH with package management

This action provides the following functionality for GitHub Actions users:

Installing a version of Typst and adding it to the PATH
Caching packages dependencies
Downloading ZIP archives as packages

- uses: typst-community/setup-typst@v5
- run: typst compile paper.typ paper.pdf

Usage

Basic Usage

name: Render paper.pdf
on: push
jobs:
  render-paper:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - uses: typst-community/setup-typst@v5
      # 🎉 Now Typst is installed!
      - run: typst compile paper.typ paper.pdf

Inputs

Installing A Typst Version

typst-version: Version range or exact version of Typst to use, using SemVer's version range syntax. Uses the latest version if unset.
allow-prereleases: When true, a version range including latest passed to typst-version input will match prerelease versions. executable-name: Used to specify the executable file name of Typst.

# Example 1
- uses: typst-community/setup-typst@v5
  with:
    typst-version: ^0.14.0

# Example 2
- uses: typst-community/setup-typst@v5
  with:
    typst-version: 0.14.0-rc1
    allow-prereleases: true

# Example 3
- uses: typst-community/setup-typst@v5
  with:
    executable-name: typst-latest

Tip

executable-name defaults to typst.
A Typst executable named typst-${version} is always kept.
For Windows, there is no need to include the executable file extension .exe in the parameters.
Multiple distinct executable-name values can be set for the same Typst version.
Setting the same executable-name (including the default typst) for different Typst versions is not recommended, as it may lead to version management confusion.

Installing Multiple Typst Versions

typst-versions-map: Used to specify a JSON map of executable names to Typst version configurations, for installing multiple Typst versions at once. Each value is an object with a required version field and an optional allowPrerelease field.

Note

When typst-versions-map is set, typst-version and executable-name are ignored. The allow-prereleases input is used as the default value for all entries in the map, but can be overridden by allowPrerelease in each individual config object.

- uses: typst-community/setup-typst@v5
  with:
    typst-versions-map: |
      {
        "typst-latest": {"version": "latest"},
        "typst-013": {
          "version": "v0.13",
          "allowPrerelease": true
        }
      }

Managing Packages with Cache

cache-dependency-path: Used to specify the path to a Typst file containing lines of import keyword.

# Example workflow YAML file
- uses: typst-community/setup-typst@v5
  with:
    cache-dependency-path: requirements.typ

// Example Typst file (requirements.typ)
#import "@preview/example:0.1.0": *

ZIP Archive Packages Management

zip-packages: Used to specify the path to a JSON file containing names and ZIP archive URLs of packages.
cache-local-packages: When true, local packages set by zip-packages will be cached independently of @preview packages.

# Example workflow YAML file
- uses: typst-community/setup-typst@v5
  with:
    zip-packages: requirements.json
    cache-local-packages: true

// Example JSON file (requirements.json)
{
  "preview": {
    "algorithmic": "https://github.com/typst-community/typst-algorithmic/archive/refs/tags/v1.0.0.zip"
  },
  "local": {
    "glossarium": "https://github.com/typst-community/glossarium/archive/refs/tags/v0.5.7.zip"
  }
}

Tip

For links to download GitHub repositories, please refer to Downloading source code archives.
The supported namespaces are only local and preview.
The SemVer versions of packages are read from its typst.toml.

Token

token: The token used to authenticate when fetching Typst distributions from typst/typst. When running this action on github.com, the default value is sufficient. When running on GHES, you can pass a personal access token for github.com if you are experiencing rate limiting.

Integration with Other Actions

Uploading Artifacts

If you require storing and sharing data from a workflow, you can use artifacts.

- uses: typst-community/setup-typst@v5
- run: typst compile paper.typ paper.pdf
- uses: actions/upload-artifact@v6
  with:
    name: paper
    path: paper.pdf

Installing Fonts with Fontist

If you require installing fonts in GitHub Actions runner, you can use Fontist.

- uses: fontist/setup-fontist@v2
- run: fontist install "Fira Code"
- uses: typst-community/setup-typst@v5
- run: typst compile paper.typ paper.pdf --font-path ~/.fontist/fonts

Development Guide

Prerequisites

Setup Typst uses TypeScript for development, so you'll need Node.js 20 and npm to develop the action.

Initial Setup

You can clone the repository with the help of Git and use npm ci to install dependencies.

Building

The action uses TypeScript for development and ncc to compile and bundle everything into a single JavaScript file for distribution.

To build the action, run npm run build. This command compiles the TypeScript code from src/main.ts and bundles it with all dependencies into the dist/main.js file.

You can also use npm run lint to run type checking and format code with npm run format.

Testing

The repository uses GitHub Actions for continuous integration testing. The workflow automatically runs on pull requests and pushes to the main branch.