Generating PDFs server-side typically means wrestling with Lambda cold starts, managing Chromium binaries, or dealing with third-party APIs that add latency and cost. If you've ever spun up a 1GB+ Docker container just to convert HTML to PDF, you know the pain.
[Cloudflare Browser Rendering](https://developers.cloudflare.com/browser-rendering/) flips this model. It's a managed headless Chromium service that runs on Cloudflare's edge network, i.e. no binaries to bundle, no cold starts, no Docker layers. You get Puppeteer-compatible APIs that execute in a globally distributed network with sub-100ms startup times.
In this guide, you'll build a production-ready PDF generation system using Astro, Cloudflare KV and Cloudflare Workers. You'll create printable receipt pages with custom CSS, wire up an API endpoint that launches headless Chrome at the edge, and cache the results in Cloudflare KV to avoid redundant rendering.
- [View example project on GitHub](https://github.com/rishi-raj-jain/my-astro-kv-pdf-app)
## Prerequisites
You'll need:
- [Node.js 20](https://nodejs.org/en/blog/announcements/v20-release-announce) or later
- A [Cloudflare](https://dash.cloudflare.com/sign-up) account
## Why Cloudflare Browser Rendering for PDFs?
- **No Chromium babysitting**: Cloudflare runs and patches headless Chromium for you.
- **Edge locality**: Render PDFs close to the requester; great for dashboards, invoices, and OG images.
- **Streaming**: Send PDFs directly from the worker without temp files.
- **Cost-aware**: Pay for usage without maintaining a fleet of renderers.
## Architecture overview
```
1. Astro Page (src/pages/receipt/[id].astro)
→ SSR route that renders your receipt/invoice HTML + print CSS
2. PDF API (src/pages/api/pdf/[id].ts)
→ Creates a Browser Rendering session
→ Loads the Astro route URL
→ Calls page.pdf() and streams the binary
3. Cloudflare Adapter + Browser binding
→ Deploys Astro to Workers/Pages
→ Provides a BROWSER binding to the worker
```
## Create a new Astro application
Let's get started by creating a new Astro project. Execute the following command:
```bash
npm create astro@latest my-astro-kv-pdf-app
cd my-astro-kv-pdf-app
npm install wrangler @cloudflare/puppeteer
```
When prompted, choose:
- `Use minimal (empty) template` when prompted on how to start the new project.
- `Yes` when prompted to install dependencies.
- `Yes` when prompted to initialize a git repository.
Once that's done, you can move into the project directory and start the app:
```bash
npm run dev
```
The app should be running on [localhost:4321](http://localhost:4321/).
## Integrate Cloudflare adapter in your Astro project
To deploy your Astro project to Cloudflare Workers and use Cloudflare KV, you need to install the Cloudflare adapter. Execute the command below:
```bash
npx astro add cloudflare --yes
```
Update `astro.config.mjs` to have **output** as **server**:
```javascript
// File: astro.config.mjs
import { defineConfig } from 'astro/config';
import cloudflare from '@astrojs/cloudflare';
export default defineConfig({
output: 'server',
adapter: cloudflare()
});
```
## Configure Browser Rendering in wrangler.jsonc
Add a BROWSER binding so the worker can launch headless Chromium:
```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"
}
}
```
> The `browser` block provisions Cloudflare's Browser Rendering service and exposes it to your worker as `env.BROWSER`.
## Add KV for caching
Create a KV namespace to cache generated PDFs:
```bash
npx wrangler kv namespace create PDF_CACHE
```
This will output an `id` that you'll add to `wrangler.jsonc`. Update the file to include the 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
}
]
}
```
## Add TypeScript types
Create `src/env.d.ts` to add proper types for the Cloudflare bindings:
```typescript
// File: src/env.d.ts
/// Issued to {order.customer}
| Item | Price |
|---|---|
| {item.name} | {item.price} |
Total: {order.total}
``` Save it as `src/pages/receipt/[id].astro`. The print CSS (`@page`) sets margins, and the `@media print` rules remove noisy link decorations. ## Create the PDF API route Here's how to create a Worker-style API route that uses Cloudflare's browser rendering to generate and cache a PDF version of your Astro HTML receipt page. We'll set up an API endpoint (`src/pages/api/pdf/[id].ts`) that: - checks if a PDF is already cached in Cloudflare KV and returns it immediately if available - launches a headless browser via the Cloudflare Browser Rendering API if not cached - navigates to the printable page and generates a PDF - stores the resulting PDF in KV for 7 days for future requests ```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