Skip to content

Automagically resolve Rheo packages from #import statements in content#124

Merged
breezykermo merged 17 commits into
mainfrom
feat/autopackage
May 15, 2026
Merged

Automagically resolve Rheo packages from #import statements in content#124
breezykermo merged 17 commits into
mainfrom
feat/autopackage

Conversation

@breezykermo
Copy link
Copy Markdown
Contributor

@breezykermo breezykermo commented May 14, 2026

Rheo's packaging system makes use of Typst's packaging format by adding a [tool.rheo] section as third-party metadata. When this section exists in a Typst package, Rheo will parse it in order to transfer the appropriate additional assets from the package into the build folder.

Since #123, a package in Rheo is syntatic sugar for an assets block (as per #122). Thus the [tool.rheo] section in the Typst package manifest ultimately specifies the options for such an assets block with a derived dest attribute. For example, say that the following manifest section exists in typst.toml in a ~/.local/share/typst/packages/rheo/slides folder:

[tool.rheo.html]
js_scripts = "index.js"

Rheo will derive the following assets block associated with this package:

[[html.assets]]
dest = "rheo/slides" # namespace and package name
js_scripts = "~/.local/share/typst/packages/rheo/slides/index.js"

All fields that are valid in an [[{format}.assets]] block are valid in a [tool.rheo.{format}] block.

Package cache pre-warm for preview namespace

The current behavior of the Typst CLI is to pre-warm packages that correspond to an #import "@preview/package-name" statement (only for the @preview namespace). Because Rheo configures and loads asset blocks before deferring to Typst compilation, we need to explicitly pre-warm the preview namespace with the corresponding packages on Typst Universe. This ensures the automagic inclusion of packages that specify Rheo configuration that are hosted on Typst Universe. In other words, if the content in a Rheo project includes the following line:

#import "@preview/rheo-library";

And rheo-library specifies some [tool.rheo] config in its manifest, Rheo will appropriately register the assets and produce them in the build. This means that Rheo packages can be distributed simply as Typst packages (with one extra config block in the package manifest).

@rheo packages

These changes allow us to externalize some of the previous examples (tooltip and slides) into a separate rheo-packages repository. So as not to require upstreaming all new packages to Typst Universe, I have decided to locate these in a @rheo namespace. This means that the packages are not auto-magically installed by the rheo or typst CLIs: but they are easily 'installed' via a git clone operation, as the rheo-packages repo is structured as a Typst package namespace. This PR also thus adds this install step to the CI, so that the examples directories can use packages from the @rheo namespace.

@breezykermo breezykermo changed the title Feat/autopackage Automagically resolve Rheo packages from #import statements in content May 15, 2026
@breezykermo breezykermo marked this pull request as ready for review May 15, 2026 10:27
@breezykermo breezykermo merged commit a4793a3 into main May 15, 2026
8 checks passed
@breezykermo breezykermo deleted the feat/autopackage branch May 15, 2026 12:57
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant