FAQ

General

What is Better Reports?

Better Reports is a self-hosted PDF report generation application. You write templates in Typst (a modern typesetting language), provide JSON data, and get production-ready PDFs.

Do I need an internet connection?

No. Better Reports runs entirely locally with no external service dependencies. All compilation happens on your machine.

Is Chromium required?

No. Unlike many PDF generation tools, Better Reports uses Typst — a native Rust typesetting engine — so no Chromium or browser rendering is needed.

Installation

Why do I need Rust installed?

Typst compilation is handled by a native Rust addon via NAPI-RS. Rust is only needed to build the addon; pre-built binaries may be available in the future.

Can I run it on Windows?

Yes, though WSL2 is recommended for production deployments. The development server works natively on Windows.

Templates

How do I pass data to a template?

JSON data is injected via the sys.inputs mechanism:

#let data = json.decode(sys.inputs.at("data"))

Can I use custom fonts?

Yes. Upload .ttf, .otf, or .ttc files to the Assets page. They are automatically detected and available in your templates.

How do I organize templates?

Use folders. Templates in subfolders are accessed with path notation: "folder/template-name".

Performance

How many concurrent compilations are supported?

The worker pool size is configurable (default: 2). Compilation requests are queued and processed by available workers.

Are compiled PDFs cached?

Yes. An LRU cache (default: 100 entries) stores recently compiled PDFs. Cache size is configurable via CACHE_SIZE.

Troubleshooting

Compilation fails with "package not found"

The app can auto-install missing packages. Run:

curl -X POST http://localhost:3000/api/packages/check \
  -H "Content-Type: application/json" \
  -d '{"template": "your-template"}'

PDF preview doesn't load in the browser

Ensure your browser supports PDF.js. Modern browsers (Chrome, Firefox, Edge) should work. Check the browser console for errors.

Port 3000 is already in use

Change the port with the PORT environment variable:

PORT=4000 node src/server.mjs

Upload fails with 413 Payload Too Large

The default upload limit is 50MB. Increase it by modifying the server configuration.