typstwatch

A small helper script for live-previewing Typst documents as PDFs.

typstwatch is a simple Bash wrapper around typst watch that

• renders your .typ file to a PDF in a temporary directory,
• opens that PDF in a viewer (priority: CLI argument, then $TYPSTWATCH_VIEWER environment variable),
• automatically cleans up the temporary files when the viewer is closed or the script exits.

By default it runs quietly with no terminal output, which makes it convenient to start in the background. A --verbose mode is available for interactive use.

---

Features

• Live preview of Typst documents using typst watch.
• PDF output stored in a temporary directory (no clutter in your project).
• Automatic cleanup of the temporary PDF and directory on exit.
• Support for TYPSTWATCH_VIEWER environment variable or custom viewer argument.
• Quiet mode by default (stdout/stderr suppressed) for background usage.
• Verbose mode (-v / --verbose) to see progress and debug output.

---

Requirements

• bash
• typst
• A PDF viewer installed and available on your PATH.
  • Recommendation: sioyek
  • You must either pass the viewer as an argument or set the TYPSTWATCH_VIEWER environment variable.

You can also use other viewers such as zathura, okular, evince, skim, or a browser that blocks until the window closes.

---

Installation

Clone or download this repository and copy the script into a directory on your PATH, for example /usr/local/bin:

# Clone the repository
git clone https://github.com/your-username/typstwatch.git
cd typstwatch

# Make the script executable
chmod +x typstwatch.sh

# Install into /usr/local/bin (may require sudo)
sudo cp typstwatch.sh /usr/local/bin/typstwatch

Now typstwatch should be available globally:

typstwatch --help

---

Usage

Basic syntax:

typstwatch [-v|--verbose] <file.typ> [pdf_viewer]

• <file.typ> – the Typst source file to watch and compile.
• [pdf_viewer] – optional PDF viewer command; defaults to $TYPSTWATCH_VIEWER if set.
• -v, --verbose – enable verbose mode.

Quiet mode (default)

When run without -v / --verbose:

• All stdout/stderr from the script and typst watch is suppressed.
• This is convenient for running in the background (e.g. from an editor or terminal).
• Cleanup still happens automatically when the viewer exits.

Example:

# Use viewer specified in TYPSTWATCH_VIEWER
export TYPSTWATCH_VIEWER=sioyek
typstwatch main.typ &

# Override with another viewer
typstwatch main.typ zathura &

Verbose mode

When run with -v or --verbose:

• The script prints what it is doing (creating temp directory, starting typst watch, PIDs, cleanup, etc.).
• Ctrl+C in the terminal immediately stops the script, kills the typst watch process, and cleans up the temporary files.

Examples:

# Verbose mode using TYPSTWATCH_VIEWER
export TYPSTWATCH_VIEWER=sioyek
typstwatch -v main.typ

# Verbose mode with a custom viewer argument
typstwatch main.typ zathura --verbose

---

How it works

1. Validates that:
   • the input .typ file exists,
   • typst is installed,
   • the requested PDF viewer command exists.
2. Creates a temporary directory via mktemp -d and sets the output PDF path inside it.
3. Starts typst watch <input.typ> <output.pdf> in the background and remembers its PID.
4. Launches the PDF viewer with the generated PDF and waits for the viewer to exit.
5. On exit (either when the viewer closes or you press Ctrl+C in verbose mode), a cleanup handler:
   • kills the typst watch process,
   • removes the temporary PDF file and directory.

This keeps your project directory clean while still giving you a fast, live-updating Typst preview.

---

License

This project is distributed under the terms of the MIT License. See LICENSE for details.