🤝 Contributing¶

Prerequisites¶

Python 3.14+
Node.js (for vendored JS and linters)
Typst CLI
Git

Project setup¶

Clone the repository and create a virtual environment:

git clone https://github.com/confirm/typarr.git
cd typarr
make venv
source .venv/bin/activate
make develop

make develop installs the Python package in editable mode (with dev dependencies) and the Node.js dependencies.

Running the dev server¶

Start the development server with auto-reload:

make server

This launches Uvicorn on http://localhost:8000 with hot-reload enabled. To skip authentication during development, set:

TYPARR_AUTH_DISABLED=true make server

Vendored assets¶

Some front-end libraries (Prism.js, Yjs) are bundled into the typarr/static/js/vendor/ directory. After modifying typarr/static/js/yjs-entry.js or updating Node dependencies, rebuild with:

make vendor-js

The colours CSS is fetched separately:

make vendor-css

Linting¶

Run all linters at once:

make test

Or run them individually:

make test-pycodestyle   # PEP 8
make test-pylint        # Pylint
make test-isort         # import order
make test-eslint        # JavaScript
make test-stylelint     # CSS

Building the docs¶

Build the documentation once:

make docs

Or start a live-reloading preview:

make autodocs

This opens the docs in your browser on http://localhost:8888 and watches for changes.

Building the Docker image¶

make package
make docker-image

make package creates a wheel in build/, which the Dockerfile copies into the image.

Project layout¶

typarr/
├── auth.py             Authentication & OIDC
├── config.py           Environment-based configuration
├── dependencies.py     FastAPI dependency injection
├── middleware.py        ASGI middleware stack
├── models.py           Pydantic request/response schemas
├── routers/            API endpoint modules
├── services/           Business logic (bucket, file, git, compiler, …)
└── static/             SPA frontend
    ├── css/
    ├── js/             ES modules (no framework, vanilla JS)
    └── index.html