Create package/template

This page covers how to build and publish a package or template on TPIX, and the rules that apply to namespaces, licences, and versions.

1. Create your package

A TPIX package is a directory containing a typst.toml manifest and your Typst source files. There are three ways to create one.

With the TPIX CLI (recommended)

Scaffold a package or template skeleton with tpix new:

# create a package
tpix new -d ~/work -n my-namespace my-package-name

# create a template
tpix new -d ~/work -t -n my-namespace my-template-name

It sets up the directory layout, a starter manifest and an entrypoint file. See the TPIX Client page for the full options.

With Typstify

Typstify can create packages and templates from its UI, with built-in package management and live preview.

Manually (not recommended)

Create the directory and files yourself.

A package needs a manifest and an entrypoint file:

my-package/
  typst.toml        # Package manifest
  lib.typ           # Entrypoint file
  README.md         # Documentation
  LICENSE           # License file

A template keeps its files in a template/ directory and declares a [template] section in typst.toml, including a preview thumbnail:

my-template/
  typst.toml
  template/
    main.typ        # Template entrypoint
    thumbnail.png   # Preview thumbnail (required for templates)
    ...

[template]
path = "template"
entrypoint = "main.typ"
thumbnail = "thumbnail.png"

Manual setup is easy to get wrong (entrypoint, exclusions, required manifest fields, thumbnail) — prefer tpix new unless you already know the format well.

2. Write the manifest

The manifest follows the same typst.toml format as official Typst packages:

[package]
name = "my-package"
version = "1.0.0"
entrypoint = "lib.typ"
authors = ["Your Name"]
license = "MIT"
description = "A brief description of the package."

You can also specify files to exclude from the archive:

[package]
# ... other fields
exclude = [".git", "*.test", "node_modules/"]

For a template, the layout files live in a template/ directory and are declared in a [template] section (with a thumbnail so the template can be previewed):

[package]
name = "my-template"
version = "1.0.0"
entrypoint = "lib.typ"
authors = ["Your Name"]
license = "MIT"
description = "A brief description."

[template]
path = "template"
entrypoint = "main.typ"
thumbnail = "thumbnail.png"

For the full manifest specification, refer to the official Typst packaging docs.

3. Bundle the package

Use the TPIX CLI to create a .tar.gz archive:

tpix bundle ./my-package

This validates the manifest and produces an archive ready for upload. You can also specify an output path or additional exclusions:

tpix bundle ./my-package -o my-package.tar.gz -e ".git" -e "node_modules/"

4. Upload to TPIX

Upload the archive to a namespace you have write access to. You can do this from the website or the CLI:

Website — open the Upload page, pick the target namespace and drop the .tar.gz file.

CLI — tpix push:

tpix push my-package.tar.gz mynamespace

After upload, TPIX validates the package (structure, manifest fields, and security checks) and makes it available in the namespace.

Can I publish the same version twice?

A published version is immutable: uploading the same version again is rejected. To ship changes, publish a new version with an incremented number. If you need to replace a version during early development, a namespace owner can enable version overwriting in the namespace settings.

TPIX packages vs official Typst packages

TPIX packages are fully compatible with Typst Universe packages: they use the same typst.toml manifest format, the same entrypoint rules, and the same set of categories and disciplines. Anything you publish to the official registry can be published to TPIX unchanged.

The differences are about the registry, not the package format:

	Official Typst Universe	TPIX
Manifest format	`typst.toml`	Same `typst.toml` format
Categories & disciplines	Predefined lists (max 3 categories)	Same categories and disciplines as official Typst packages
Namespace	`@preview` only	Custom namespaces (`@myteam`, `@company`, etc.)
Visibility	Public only	Configurable (public or private)
Fonts	Not loaded from packages — Typst only uses `--font-path` / `TYPST_FONT_PATHS` / system / embedded fonts	Same for packages; templates can ship fonts in `template/`, which `typst init` copies into the workspace
Package size	Recommended to be small	More generous size limits
Licensing	Follows specific guidelines (OSI-approved or CC licenses)	Flexible license options
Auto-download	Typst compiler fetches automatically	Requires the TPIX CLI or Typstify to download first
Publishing	Submit via GitHub PR to `typst/packages`	Upload directly with the website or `tpix push`
Access control	None (everything is public)	Namespace-level permissions (read/write/owner)
Naming rules	Cannot use "obvious" names (e.g., `slides`), cannot contain "typst"	Same naming rules as official Typst packages

Fonts

Typst never scans package contents for fonts. When you compile locally, the Typst CLI looks only in these places:

Explicit paths — directories passed with --font-path.
Environment paths — directories listed in TYPST_FONT_PATHS.
System fonts — your operating system's global font directories (e.g. C:\Windows\Fonts, /Library/Fonts).
Embedded fonts — a few default fonts baked into the compiler binary (such as Libertinus Serif and DejaVu Sans Mono).

Because none of these is a package, shipping fonts inside a package is not a supported or endorsed way to distribute them: a .ttf / .otf in an archive is not discovered, and every user would still have to install the font or add its directory to a font path themselves.

Templates are the exception in practice. typst init copies everything in a template's template/ directory into the user's working directory. A template can therefore ship the fonts it depends on alongside its files (usually under template/), and tools that consume TPIX templates — such as Typstify — can copy them into the workspace and make them available. Any other application integrating with TPIX can use the same mechanism to distribute fonts that a template needs.

Supported licenses

TPIX supports a wide range of licenses. While the official Typst Universe follows specific license guidelines, TPIX offers more flexibility. When specifying the license field in your typst.toml, you can use:

SPDX license identifiers

Most common open-source licenses are supported via SPDX identifiers:

[package]
name = "my-package"
version = "1.0.0"
license = "MIT"           # MIT License
# license = "Apache-2.0"  # Apache License 2.0
# license = "GPL-3.0"     # GNU General Public License v3.0
# license = "BSD-3-Clause" # BSD 3-Clause
# license = "ISC"          # ISC License
# license = "MPL-2.0"     # Mozilla Public License 2.0

TPIX validates your license against the official SPDX list. If the license identifier is not recognized, you'll see a warning but the package can still be uploaded.

Proprietary and unlicensed

For private or commercial packages, you can use:

[package]
# For proprietary/closed-source packages
license = "Proprietary"

# For packages with no license (all rights reserved)
license = "UNLICENSED"

Custom licenses with LicenseRef

For non-standard or custom licenses, use the SPDX LicenseRef- prefix followed by your license name:

[package]
# For a custom or proprietary license
license = "LicenseRef-MyCompany-Internal"

# Or combine with standard licenses using SPDX expressions
# license = "MIT AND LicenseRef-MyCompany-Internal"

This is the official SPDX way to reference custom licenses. Include the full license text in a LICENSE file in your package so users can understand your terms.

License file

While the license field in typst.toml is required, we also recommend including a LICENSE file in your package archive for clarity:

my-package/
  typst.toml
  lib.typ
  LICENSE          # Full license text (recommended)

This makes it easier for users to understand your terms when they download and use your package.

Namespaces

Packages on TPIX are organized into namespaces. Each namespace has its own package index and access control. TPIX does not distinguish between user and team namespaces — any namespace can have multiple members with different permission levels.

@preview — mirrors the official Typst Universe (read-only, updated automatically).
Custom namespaces — created by users for personal or team use. Invite members and assign read, write, or owner permissions as needed.

Registered users can create public or private namespaces and invite members with read, write, or owner permissions. Default limits (adjustable per user by administrators) are 3 namespaces per user and 10 members per namespace including the owner. You can manage namespaces from the Namespaces page or via the TPIX CLI.

Package versions

Version numbers follow semantic versioning. Since versions are immutable by default (see the upload section above), increment the version whenever you change a package — this keeps downstream builds reproducible.

Account limits

TPIX is free to use. Each user gets default limits that administrators can adjust per user:

Up to 3 namespaces (public or private).
Up to 10 members per namespace (including the owner).
Up to 200MB of storage per namespace.
Up to 10MB per package archive.
30 REST API requests per minute by default.
Up to 10 API keys per user by default.

For larger teams or high-frequency CI/CD usage, contact the administrators for a custom quota.