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.

Authentication

What are the default credentials?

If no credentials are configured via env vars or .credentials.json, the server uses admin / password123.

How do I change the password?

Log in with the default credentials, click the settings icon in the header, and use the Change Password option. Or use the API:

curl -X POST http://localhost:3000/api/change-password \
  -H "Content-Type: application/json" \
  -H "Authorization: Basic $(echo -n '\''admin:password123'\'' | base64)" \
  -d '\''{"currentPassword": "password123", "newPassword": "my-new-password"}'\''

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 customize the variable name?

Yes. Use the variableName parameter in the report or preview API:

curl -X POST http://localhost:3000/api/report \
  -d '\''{"template": "my-report", "variableName": "myData", "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".

How are templates saved?

Templates are saved as .typ files on disk. Metadata (title, description, example data) is stored in adjacent .json files.

Performance

How many concurrent compilations are supported?

The worker pool size is configurable via REPORTS_POOL_SIZE (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 REPORTS_CACHE_SIZE.

Troubleshooting

Compilation fails with "package not found"

The app can auto-install missing packages (up to 3 retries). Run:

curl -X POST http://localhost:3000/api/packages/check \
  -H "Content-Type: application/json" \
  -d '\''{"templateContent": "#import \"@preview/iconify:0.4.0\": icon"}'\''

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 REPORTS_PORT environment variable:

REPORTS_PORT=4000 node src/server.mjs

Upload fails with 413 Payload Too Large

The default upload limit is 10 MB. Increase it with REPORTS_MAX_BODY_SIZE (value in bytes):

REPORTS_MAX_BODY_SIZE=52428800 node src/server.mjs