Typst Package Creation

Package structure

my-package/
├── typst.toml          # manifest
├── lib.typ             # entrypoint (default name)
├── README.md           # documentation
├── LICENSE             # license file
├── examples/
│   └── basic.typ       # usage examples
└── tests/
    └── test-basic.typ  # tests

typst.toml manifest

[package]
name = "my-package"
version = "0.1.0"
entrypoint = "lib.typ"
authors = ["Your Name <you@example.com>"]
license = "MIT"
description = "A short, clear description of what this package does"
homepage = "https://github.com/yourname/my-package"
repository = "https://github.com/yourname/my-package"
keywords = ["academic", "papers", "templates"]
categories = ["templates"]
exclude = ["tests/**", "*.png"]    # files to exclude from package

Example package: a custom callout block

// lib.typ
#let callout(body, kind: "info") = {
  let colors = (
    info: (rgb("#e3f2fd"), rgb("#1976d2")),
    warning: (rgb("#fff8e1"), rgb("#f9a825")),
    danger: (rgb("#ffebee"), rgb("#c62828")),
  )
  let (bg, fg) = colors.at(kind)
  block(
    fill: bg,
    stroke: 1pt + fg,
    inset: 8pt,
    radius: 4pt,
    body,
  )
}

#let info(body) = callout(body, kind: "info")
#let warning(body) = callout(body, kind: "warning")
#let danger(body) = callout(body, kind: "danger")

Test locally with @local

# Install to local namespace
# Linux/Mac:
mkdir -p ~/.local/share/typst/packages/local/my-callouts/0.1.0
cp -r my-package/* ~/.local/share/typst/packages/local/my-callouts/0.1.0/

# Windows:
# %APPDATA%\typst\packages\local\my-callouts\0.1.0\

# Now use in any document
#import "@local/my-callouts:0.1.0": *

#info[Standard info note]
#warning[Watch out!]
#danger[Critical issue]

Publishing to @preview

1. Fork github.com/typst/packages
2. Add your package under packages/preview/PACKAGE/VERSION/
3. Open a Pull Request with title my-package:0.1.0
4. Address review comments from the curators
5. Wait for merge (usually days to a week)
6. After merge, @preview/my-package:0.1.0 is publicly available

Bumping versions

Each version is a new directory. To release 0.2.0:

• Update version = "0.2.0" in typst.toml
• Submit PR adding packages/preview/PACKAGE/0.2.0/ (don't modify 0.1.0 — old versions stay available)
• Users pinned to 0.1.0 keep working; users pinned to 0.2.0 get the new version

Common mistakes

• Mutating a published version. Once 0.1.0 is published, it's frozen. Bump to 0.1.1 for any change.
• Missing license file. Required by curators. Even for permissive licenses, include a LICENSE file.
• Functions exported but not documented. Curators expect a README explaining the public API.
• Pinning to latest. Typst doesn't have latest. Always pin to a specific version.