TypeScript-Client

Der TypeScript-Client ruft die Brevier-Engine aus Node.js auf. Sie übergeben HTML und Daten und bekommen das PDF zurück. Er braucht Node.js 22 oder neuer. Die Engine übernimmt das Layout, Sie schreiben keinen Code zum Zeichnen von PDFs.

Es gibt zwei Betriebsarten:

Engine installieren

Die Engine ist der Befehl brevier. Der Kindprozess-Modus startet ihn, er muss also im PATH des Rechners liegen, auf dem Ihr Node.js-Code läuft:

pip install brevier

Weitere Wege zur Installation stehen auf der Seite Installation.

Testschlüssel holen

Jede Erzeugung braucht einen Lizenzschlüssel, auch zum Testen. Holen Sie den Schlüssel vor der ersten Erzeugung.

1. Fordern Sie auf der Preisseite einen kostenlosen Testschlüssel für 30 Tage an. Er kommt per E-Mail.
2. Setzen Sie die Umgebungsvariable BREVIER_LICENCE_KEY:

export BREVIER_LICENCE_KEY="<ihr-lizenzschluessel>"

$env:BREVIER_LICENCE_KEY = "<ihr-lizenzschluessel>"

Die Engine liest den Schlüssel aus ihrer Umgebung. Der Client gibt Ihre Umgebung an den Kindprozess weiter. Im Serve-Modus setzen Sie den Schlüssel in der Shell, die brevier serve startet.

Client hinzufügen

npm install brevier

Kindprozess

Dieses Programm erzeugt ein PDF aus einem HTML-Text und einem Objekt:

import { Pdf } from 'brevier';

async function main(): Promise<void> {
    await Pdf.builder()
        .withHtml('<h1>Hello {{ name }}</h1>')
        .withData({ name: 'World' })
        .toFile('hello.pdf');
}

main();

Übersetzen Sie es mit tsc und starten Sie es mit node. Im Ordner liegt jetzt hello.pdf.

• withHtml und withCss nehmen das Layout als Text. withHtmlFile und withCssFile lesen es aus einer Datei.
• withData nimmt jedes Objekt. withJson nimmt JSON-Text.
• toBytes gibt das PDF zurück. toFile schreibt es in einen Pfad.

Serve-Modus

Im Serve-Modus läuft die Engine als Dienst, und Ihr Code fragt sie mit dem Namen einer Vorlage nach einem PDF. Eine Vorlage ist ein Ordner mit einer Datei gleichen Namens:

<!DOCTYPE html>
<html lang="en">
<body>
  <h1>Hello {{ name }}</h1>
</body>
</html>

Starten Sie den Server in dem Ordner, der templates enthält:

brevier serve --templates templates

Der Server lauscht auf 127.0.0.1:8080. Er hat weder TLS noch eine Anmeldung. Stellen Sie ein Gateway davor, bevor Sie ihn nach außen öffnen. Dann erzeugen Sie die Vorlage aus Node.js:

import { writeFile } from 'node:fs/promises';
import { template } from 'brevier';

async function main(): Promise<void> {
    const pdf = await template('hello', { url: 'http://127.0.0.1:8080' })
        .with('name', 'World')
        .render();
    await writeFile('hello.pdf', pdf);
}

main();

• with(name, value) setzt eine Wurzel der Vorlage. with(map) setzt mehrere.
• rows(list) setzt die Zeilen einer Tabelle.
• render({ konto, buchungen }) bindet jeden Schlüssel an eine Wurzel der Vorlage.
• Ohne url liest der Client die Umgebungsvariable BREVIER_URL. Ohne sie startet er brevier serve --stdio als Kindprozess. Er liest den Ordner templates des Arbeitsverzeichnisses und nutzt den Prozess weiter.

Wie erzeuge ich viele PDFs auf einmal?

Pdf.batch() macht aus jeder HTML-Datei eines Ordners und seiner Unterordner ein PDF. Alle Dateien bekommen dasselbe CSS. Der Batch übergibt keine Daten: Jede Datei muss schon die fertige Seite sein, zum Beispiel aus Ihrer eigenen Template-Engine.

import { Pdf } from 'brevier';

async function main(): Promise<void> {
    const batch = await Pdf.batch().withInput('briefe', '*.html').withCssFile('firma.css');
    const written = await batch.withOutput('out').toFiles();
    written.forEach((file) => console.log(file));
}

main();

Mit briefe/2026-001.html und briefe/2026-002.html gibt das Programm eine Zeile je geschriebenem PDF aus, in der Reihenfolge, in der es die Dateien findet:

out/2026-001.pdf
out/2026-002.pdf

Für ein PDF je Datensatz rufen Sie stattdessen Pdf.builder() in einer Schleife auf. Ein Unterordner von briefe erscheint als derselbe Unterordner von out. Scheitert eine Datei, wird das Promise von toFiles mit einer BrevierException abgelehnt.

Wie liefere ich das PDF aus einem Web-Endpunkt aus?

Erzeugen Sie einen Buffer und senden Sie ihn mit dem Inhaltstyp application/pdf. In Express:

import express from 'express';
import { template } from 'brevier';

const app = express();

app.get('/invoices/:id/pdf', async (req, res) => {
    const rechnung = await invoices.find(req.params.id);
    const pdf = await template('rechnung').render({ rechnung });
    res.type('application/pdf').send(pdf);
});

invoices steht für Ihren eigenen Datenzugriff. Setzen Sie BREVIER_URL auf dem Server, dann geht jeder Aufruf an Ihr laufendes brevier serve. Der Code ändert sich nicht.

Wie bekomme ich HTML statt eines PDFs?

Html.builder() nimmt dieselben Aufrufe wie Pdf.builder() und gibt HTML zurück. Damit zeigen Sie das Dokument in einem Webportal, oder Sie vergleichen es in einem Test:

const html = await Html.builder()
    .withHtml('<h1>Hello {{ name }}</h1>')
    .withData({ name: 'World' })
    .toBytes();

Die Klassennamen dieses HTML bleiben von Version zu Version gleich. Ausgabe und Tests zeigt, wie Sie es in einem Snapshot-Test nutzen.

Einen JasperReports- oder Word-Aufruf ersetzen

Wenn Ihr Dienst heute einen JasperReports-Bericht oder eine Word-Datei füllt, importieren Sie zuerst die Vorlage. Ersetzen Sie dann den Aufruf in zwei Schritten.

Schritt 1 behält Ihr Datenobjekt und übergibt die Zeilen:

return await Brevier.template("kontoauszug").with(data).rows(buchungen).render();

Schritt 2 übergibt Ihre Objekte. Die Schlüssel des Objekts sind die Wurzeln der Vorlage.

return await Brevier.template("kontoauszug").render({ konto, kunde, buchungen });

Fehler

Der Client wirft eine BrevierException. Sie hat code, den Fehlercode der Engine wie DATA_ERROR, und path, die Stelle in den Daten, an der das Problem liegt. Die Meldung enthält nie einen Wert aus Ihren Daten.