# Tips for package authors

## Sparse checkout of the repository

Because the repository stores all versions of all packages that ever were
published, its size only grows with time. However, most of the time, you will
only work in a few specific directories (the ones for your own packages). Git
allows for "sparse checkouts", which reduce the time it takes to clone the
repository and its size on your disk.

First, make sure you have forked the repository to your own GitHub account.
Then, follow these steps to clone the repository:

```sh
git clone --depth 1 --no-checkout --filter="tree:0" git@github.com:{your-username}/packages
cd packages
git sparse-checkout init
git sparse-checkout set packages/preview/{your-package-name}
git remote add upstream git@github.com:typst/packages
git config remote.upstream.partialclonefilter tree:0
git checkout main
```

The `packages` directory you are in still corresponds to the whole repository.
Do not delete or edit the `README.md`, `LICENSE` or any other file at the root.
Instead, create the directory `packages/preview/{your-package-name}/{version}`
and copy your files here. Note that `packages/` is a directory in the
`packages` repository: if you look at the full path, there should be two
consecutive parts called `packages`.

## Don't use submodules

The Typst package repository requires the files to be actually copied
to their respective directory, they should not be included as Git submodules.

When copying a package from another Git repository, you should not copy the
`.git` folder, otherwise when creating a commit to publish your package,
Git will replace the copied files with a submodule.

## What to commit? What to exclude?

In some case, simply copying and pasting the contents of the repository in which
you developed your package to a new directory in this repository is enough to
publish a package. However, this naive approach may result in unnecessary files
being included, making the size of this repository and of the final archives
larger than they need to be.

There are two solutions to limit this problem: excluding files from the archive
(using the `exclude` key in your [package manifest][manifest]), or simply not
committing the files to this repository in the first place.

To know which strategy to apply to each file, we can split them in three groups:

__1. Required files (commit & include)__\
Files that are necessary for the package to work. If any of these files are
removed, the package would break for the end user. This includes the manifest
file, main Typst file and its dependencies, and in case of a template package,
any file in the template directory.

__2. Documentation files (commit & exclude)__\
Files that are necessary for the package to be displayed correctly on Typst
Universe. This includes the README, and any files that are linked from there
(manuals, examples, illustrations, etc.). These files can easily be accessed
by opening the package README.

__3. Other files (don't commit)__\
This generally includes test files, build scripts, but also examples or manuals
that are not linked in the README. These files would be almost impossible to
access for the final user, unless they browse this GitHub repository or their
local package cache.

The first two groups (required and documentation files) should be committed to
this repository. And files that are not strictly necessary for the package to
work (documentation files) should be excluded in `typst.toml`. They will still
be available on typst universe to link to from the README.\
The third group should simply not be committed to this repository. If you think
some of the remaining files are important, they probably belong to the second
group and should be linked in the README, so that they are easily discoverable.
A good example showing how to link examples and a manual is [CeTZ][cetz].

The only exceptions to this rule are the LICENSE file (that should always be
available along with the source code, so it should not be excluded), and the
README (which is generally a lightweight file, and can provide minimal
documentation in case the user is offline or can't access anything else than
their local package cache for some other reason).

Also note that there is no need to exclude template thumbnails: they are
automatically left out of the archive.

## Tools that can be useful

The community created some tools that can help when developing your package:

- [typst-package-check], to lint your package.
- [tytanic], to test your packages.
- [typship], to easily install your package locally or submit it to Typst Universe.

A more comprehensive list can be found in [Package development — Best of Typst (TCDM)][tcdm-pkg]
maintained by the community.

[cetz]: https://typst.app/universe/package/cetz/0.3.4
[typst-package-check]: https://github.com/typst/package-check
[tytanic]: https://typst-community.github.io/tytanic/
[typship]: https://github.com/sjfhsjfh/typship
[tcdm-pkg]: https://ydx-2147483647.github.io/best-of-typst/#pkg
[manifest]: manifest.md
