Die serverseitige PDF-Erzeugung bedeutet oft Lambda-Cold-Starts, Chromium-Binaries oder Drittanbieter-APIs mit extra Latenz und Kosten. Wer schon einmal einen Docker-Container mit über 1 GB nur für HTML-zu-PDF gestartet hat, kennt das Problem.
[Cloudflare Browser Rendering](https://developers.cloudflare.com/browser-rendering/) dreht dieses Modell um: ein verwalteter Headless-Chromium-Dienst auf Cloudflares Edge-Netzwerk, keine Binaries, keine Cold-Starts, keine Docker-Layer. Sie erhalten Puppeteer-kompatible APIs mit Startzeiten unter 100 ms, global verteilt.
In dieser Anleitung bauen Sie ein produktionsreifes PDF-System mit Astro, Cloudflare KV und Cloudflare Workers. Sie erstellen druckbare Belegseiten mit eigenem CSS, verdrahten einen API-Endpunkt, der Headless Chrome am Edge startet, und cachen die Ergebnisse in Cloudflare KV, um doppeltes Rendering zu vermeiden.
- [Beispielprojekt auf GitHub ansehen](https://github.com/rishi-raj-jain/my-astro-kv-pdf-app)
## Voraussetzungen
Sie benötigen:
- [Node.js 20](https://nodejs.org/en/blog/announcements/v20-release-announce) oder höher
- Ein [Cloudflare](https://dash.cloudflare.com/sign-up)-Konto
## Warum Cloudflare Browser Rendering für PDFs?
- **Kein Chromium-Pflegeaufwand**: Cloudflare betreibt und patcht Headless Chromium für Sie.
- **Edge-Nähe**: PDFs nahe am Anfragenden rendern, ideal für Dashboards, Rechnungen und OG-Bilder.
- **Streaming**: PDFs direkt aus dem Worker senden, ohne temporäre Dateien.
- **Kostenbewusst**: Nutzungsbasierte Abrechnung ohne eigene Renderer-Flotte.
## Architekturüberblick
```
1. Astro-Seite (src/pages/receipt/[id].astro)
→ SSR-Route mit Beleg-/Rechnungs-HTML + Print-CSS
2. PDF-API (src/pages/api/pdf/[id].ts)
→ Browser-Rendering-Session starten
→ Astro-Route-URL laden
→ page.pdf() aufrufen und Binary streamen
3. Cloudflare-Adapter + Browser-Binding
→ Astro auf Workers/Pages deployen
→ BROWSER-Binding für den Worker bereitstellen
```
## Neue Astro-Anwendung erstellen
Starten Sie mit einem neuen Astro-Projekt. Führen Sie aus:
```bash
npm create astro@latest my-astro-kv-pdf-app
cd my-astro-kv-pdf-app
npm install wrangler @cloudflare/puppeteer
```
Wählen Sie bei den Prompts:
- `Use minimal (empty) template`, wenn gefragt wird, wie das Projekt starten soll.
- `Yes`, wenn Abhängigkeiten installiert werden sollen.
- `Yes`, wenn ein Git-Repository initialisiert werden soll.
Danach ins Projektverzeichnis wechseln und die App starten:
```bash
npm run dev
```
Die App läuft unter [localhost:4321](http://localhost:4321/).
## Cloudflare-Adapter in Ihr Astro-Projekt integrieren
Für Cloudflare Workers und Cloudflare KV installieren Sie den Cloudflare-Adapter:
```bash
npx astro add cloudflare --yes
```
Setzen Sie in `astro.config.mjs` **output** auf **server**:
```javascript
// File: astro.config.mjs
import { defineConfig } from 'astro/config';
import cloudflare from '@astrojs/cloudflare';
export default defineConfig({
output: 'server',
adapter: cloudflare()
});
```
## Browser Rendering in wrangler.jsonc konfigurieren
Fügen Sie ein BROWSER-Binding hinzu, damit der Worker Headless Chromium starten kann:
```jsonc
// File: wrangler.jsonc
{
"main": "dist/_worker.js/index.js",
"name": "my-astro-kv-pdf-app",
"compatibility_date": "2025-12-06",
"compatibility_flags": [
"nodejs_compat",
"global_fetch_strictly_public"
],
"assets": {
"binding": "ASSETS",
"directory": "./dist"
},
"observability": {
"enabled": true
},
"browser": {
"binding": "BROWSER"
}
}
```
> Der Block `browser` stellt Cloudflares Browser-Rendering-Dienst bereit und macht ihn als `env.BROWSER` im Worker verfügbar.
## KV für Caching hinzufügen
Erstellen Sie einen KV-Namespace für generierte PDFs:
```bash
npx wrangler kv namespace create PDF_CACHE
```
Die Ausgabe enthält eine `id` für `wrangler.jsonc`. Ergänzen Sie das KV-Binding:
```jsonc
// File: wrangler.jsonc
{
"main": "dist/_worker.js/index.js",
"name": "my-astro-kv-pdf-app",
"compatibility_date": "2025-12-06",
"compatibility_flags": [
"nodejs_compat",
"global_fetch_strictly_public"
],
"assets": {
"binding": "ASSETS",
"directory": "./dist"
},
"observability": {
"enabled": true
},
"browser": {
"binding": "BROWSER"
},
"kv_namespaces": [
{
"binding": "PDF_CACHE",
"id": "generated-id",
"remote": true
}
]
}
```
## TypeScript-Typen hinzufügen
Erstellen Sie `src/env.d.ts` für die Cloudflare-Bindings:
```typescript
// File: src/env.d.ts
/// Issued to {order.customer}
| Item | Price |
|---|---|
| {item.name} | {item.price} |
Total: {order.total}
``` Speichern als `src/pages/receipt/[id].astro`. Das Print-CSS (`@page`) setzt Ränder; `@media print` entfernt störende Link-Dekorationen. ## PDF-API-Route erstellen Worker-API-Route mit Cloudflare Browser Rendering: PDF aus der Astro-HTML-Belegseite erzeugen und cachen. Unter `src/pages/api/pdf/[id].ts`: - prüfen, ob ein PDF in Cloudflare KV liegt, und es sofort zurückgeben - bei Cache-Miss Headless-Browser über Browser Rendering starten - zur druckbaren Seite navigieren und PDF erzeugen - PDF sieben Tage in KV speichern ```typescript // File: src/pages/api/pdf/[id].ts import type { APIRoute } from "astro"; import puppeteer from "@cloudflare/puppeteer"; // Helper to create a proper PDF HTTP response const pdfResponse = (pdf: Buffer