givetypst

An HTTP service that generates PDFs from Typst templates stored in S3-compatible cloud storage.

Usage

Usage: givetypst [OPTIONS]

Generate PDFs from Typst templates stored in cloud storage.

Environment Variables:
  BUCKET_URL          URL of the cloud storage bucket containing templates (required)
  PORT                HTTP port to listen on (overrides -port flag)
  MAX_TEMPLATE_SIZE   Maximum template file size in bytes (default: 1048576)
  MAX_DATA_SIZE       Maximum data file size in bytes (default: 10485760)

Options:
  -port int
        HTTP port to listen on (default 8080)
  -v    Verbose output (debug mode)
  -version
        Show version and exit

Why?

Generate PDFs on-demand from templates without managing Typst installations.

Store your Typst templates in S3-compatible storage, then call the API with template data to receive a compiled PDF. Useful for generating invoices, reports, certificates, or any document from structured data.

API

Health Check

GET /health

Returns OK if the service is running and can access the storage bucket.

Generate PDF

POST /generate
Content-Type: application/json

The request body supports three modes:

Inline Data

Small data can be passed directly in the request:

{
  "templateKey": "invoice.typ",
  "data": {
    "customer": "Acme Corp",
    "amount": "1000.00"
  }
}

Data from Bucket

Large data (e.g., full resume content) can be stored in the bucket and referenced by key:

{
  "templateKey": "resume.typ",
  "dataKey": "resumes/john-doe.json"
}

No Data

Templates that don't require external data:

{
  "templateKey": "static-document.typ"
}

Note: You cannot specify both data and dataKey in the same request.

The data (from either source) is written to data.json and can be accessed in your template via #let data = json("data.json").

Returns the generated PDF.

Docker

docker run -e BUCKET_URL=s3://my-bucket?region=us-east-1 -p 8080:8080 ghcr.io/boringbin/givetypst

Supported Storage

Any S3-compatible storage via gocloud.dev/blob:

• AWS S3
• Google Cloud Storage
• Azure Blob Storage
• MinIO
• And more

Typst Version

The Docker image defaults to Typst 0.14.2.

To use a different Typst version, build the image with the TYPST_VERSION argument:

docker build --build-arg TYPST_VERSION=0.15.0 -t givetypst .

License

MIT