Utpm

<div align="center">

Unofficial Typst Package Manager

UTPM is a powerful command-line package manager for Typst. Create, manage, and share Typst packages with ease — whether for local development or publishing to Typst Universe.

<br/>

</div>

---

✨ Quick Start

# Install UTPM (see [Installation](#-installation) for all options)
cargo install utpm

# Create a new package
utpm prj init

# Link it for local development
utpm prj link

# Use it in Typst!
# #import "@local/my-package:0.1.0": *

[!NOTE] UTPM is actively developed and growing! Some features are still in progress.
Contributions are welcome — check out our contributing guide!

🔥 Why UTPM?

• 🚀 Rapid Development - Create and link packages instantly for local testing
• 📦 Smart File Management - Respects .gitignore, .typstignore, and custom exclude patterns
• 🔄 Dependency Management - Sync dependencies and bump versions with ease
• 📊 Metadata Extraction - Extract package info for scripts and CI/CD pipelines
• 🎨 Flexible Output - JSON, HJSON, YAML, TOML, or human-readable text
• 🛡️ Try Features without Risk - Dry-run mode for all destructive operations
• ⚡ Fast & Lightweight - Written in Rust for speed and reliability

🎯 Features

Package Development

• ✨ Initialize packages with interactive prompts (utpm prj init)
• 🔗 Link packages for local development (utpm prj link)
• ⬆️ Bump versions with semantic versioning (utpm prj bump)
• 📋 Extract metadata for automation (utpm prj metadata)

Dependency Management

• 📥 Clone packages from Typst Universe (utpm prj clone)
• 🔄 Sync dependencies to latest versions (utpm prj sync)
• 📦 Install from git repositories (utpm pkg install)

Package Discovery

• 🗃️ List local packages with tree view (utpm pkg list --tree)
• ℹ️ Get package info from remote (utpm pkg get)
• 🔍 Check for updates without applying (utpm prj sync -c)

Coming Soon

• 🚀 Publish directly to Typst Universe (in development)

---

📦 Installation

Quick Install

Cargo (Cross-platform)

# Using cargo-binstall (fastest)
cargo binstall utpm

# Or build from source
cargo install utpm

Arch Linux

# Using an AUR helper (yay, paru, etc.)
yay -S utpm-bin      # Pre-built binaries
# or
yay -S utpm-git      # Build from latest git

Homebrew (macOS/Linux)

# Coming soon - waiting for tap approval
brew install typst-community/utpm/utpm

Nix

<details> <summary>📦 Nix Installation Options</summary>

With Flakes

Temporary shell:

nix shell github:typst-community/utpm

Permanent installation in flake.nix:

{
  inputs.utpm.url = "github:typst-community/utpm";
  
  outputs = { self, nixpkgs, ... }@inputs: {
    nixosConfigurations.yourhostname = nixpkgs.lib.nixosSystem {
      system = "x86_64-linux";
      modules = [{
        environment.systemPackages = [ 
          inputs.utpm.packages.${system}.default 
        ];
      }];
    };
  };
}

Without Flakes

git clone https://github.com/typst-community/utpm.git
cd utpm
nix-build
./result/bin/utpm

</details>

More Package Managers

UTPM is being packaged for multiple package managers:

• 📦 Snap - sudo snap install utpm (automated publishing)
• 📦 Flatpak - Available on Flathub (semi-automated)
• 📦 Debian/Ubuntu - .deb packages (manual, see docs/PUBLISHING.md)
• 📦 Fedora/RHEL - RPM packages (manual, see docs/PUBLISHING.md)

For maintainers: See docs/PACKAGING.md for technical details and docs/SECRETS.md for automation setup.

Note: Windows builds are generated here but scoop is managed by an another user. See Scoop bucket for typst for more infos.

From Source

git clone https://github.com/typst-community/utpm.git
cd utpm
cargo install --path .

---

🚀 Usage

GitHub Actions

Use UTPM in your CI/CD workflows:

- name: Setup UTPM
  uses: Thumuss/setup-utpm@v1

See the setup-utpm repository for complete documentation and examples.

Basic Commands

# Create a new package
utpm prj init

# Link for local development
utpm prj link

# Clone from Typst Universe
utpm prj clone @preview/example:1.0.0

# Bump version
utpm prj bump 1.2.0

# List installed packages
utpm pkg list --tree

# Get metadata for scripts
VERSION=$(utpm prj metadata -f version)

Command Overview

Project Management (utpm prj)

| Command | Alias | Description | |---------|-------|-------------| | init | n | Create a new typst.toml manifest interactively | | link | l | Link package for local development (respects ignore files) | | clone | c | Clone a package from Typst Universe | | bump | b | Bump package version (supports semantic versioning) | | sync | s | Sync dependencies to latest versions | | metadata | m | Extract metadata for scripts and automation | | publish | p | 🚧 Publish to Typst Universe (coming soon) |

Package Management (utpm pkg)

| Command | Alias | Description | |---------|-------|-------------| | list | l | List installed packages (supports tree view) | | path | p | Show package directory path | | unlink | u | Remove a linked package | | get | g | Get package info from remote | | install | i | Install package from git repository |

Other Commands

• utpm generate (g) - Generate shell completion scripts

Global Options

utpm [OPTIONS] <COMMAND>

Options:
  -v, --verbose <LEVEL>     Logging level (trace, debug, info, warn, error)
  -o, --output <FORMAT>     Output format (text, json, yaml, toml, hjson)
  -D, --dry-run             Preview changes without writing to disk
  -h, --help                Show help information
  -V, --version             Show version

💡 Tip: Use utpm <command> --help for detailed command-specific help

---

⚙️ Configuration

UTPM extends the standard typst.toml with a [tool.utpm] section for package-specific settings.

Excluding Files

Control which files are included when linking or publishing:

[package]
name = "my-package"
version = "0.1.0"
# ... other standard fields

[tool.utpm]
exclude = [
  ".git",
  ".github",
  "*.md",           # Exclude all Markdown files
  "tests/",         # Exclude tests directory
  "examples/",      # Exclude examples
  "**/*.bak",       # Exclude backup files recursively
]

Pattern Syntax:

• * - Match files in current directory (e.g., *.md)
• ** - Match recursively (e.g., **/*.tmp)
• !pattern - Negate/include pattern
• Patterns ending with / match directories only

Ignore Files Respected:

• .gitignore (default: enabled)
• .typstignore (default: enabled)
• .ignore (optional, enable with --ignore)
• Custom patterns in [tool.utpm]

Metadata Extraction

Extract package metadata for scripts and CI/CD:

# Get specific field (outputs plain text)
VERSION=$(utpm prj metadata -f version)
NAME=$(utpm prj metadata -f name)

# Use in automation
echo "Building $NAME version $VERSION"
git tag "v$VERSION"

# Get all metadata as JSON
utpm -o json prj metadata | jq '.authors'

Available fields: name, version, entrypoint, authors, license, description, repository, homepage, keywords, categories, disciplines, compiler, exclude

📄 Example: See assets/typst.toml.example for a complete configuration reference.

---

📖 Documentation

| Document | Description | |----------|-------------| | 📘 Complete Guide | Comprehensive guide for users, package authors, and contributors | | 🤝 Contributing | Code standards, testing, and contribution process | | 🛠️ Development | Development setup, workflow, and tools | | 🧪 Testing | Testing guide, running tests, and writing new tests |

---

🤝 Contributing

We welcome contributions of all kinds! Whether you're fixing bugs, adding features, or improving documentation, your help is appreciated.

Quick Start for Contributors

# 1. Install development tools
cargo install just

# 2. Setup git hooks (optional but recommended)
just setup-hooks

# 3. Before committing
just fix    # Auto-format and fix linting issues
just ci     # Run all checks (format, lint, test)

What You Can Do

• 🐛 Report bugs - Open an issue with details
• 💡 Suggest features - Share your ideas in discussions
• 📝 Improve docs - Help make documentation clearer
• 🔧 Fix issues - Pick up a "good first issue"
• ✨ Add features - Implement new functionality

See CONTRIBUTING.md for detailed guidelines on code standards, testing, and the PR process.

---

📝 License

MIT License - see LICENSE