📄 PDF Screenshot Service

Turn any PDF URL into a PNG thumbnail, stored on Cloudflare R2 and ready to serve. 🖼️☁️

Ships in two flavors: a long-running 🐎 Fastify server you can self-host (e.g. on Hetzner) and a ⚡ Vercel serverless function. Same API contract on both — pick the one that fits your hosting.

🚀 Deployment options

Path	What it is	When to use
🐎 Fastify on Hetzner (`index.ts`, `routes/`)	Long-running Fastify server, PM2-managed, runs on your own box.	Dedicated host, lowest per-request latency, full Swagger UI, predictable bill.
⚡ Vercel serverless (`vercel/`)	Vercel Function (Node 22) — `pdfjs-dist` + `canvas`, R2 via `@aws-sdk/client-s3`, optional Upstash rate-limit.	Zero ops, scale-to-zero, deploy on `git push`. ~2–3s cold start; sub-second warm.

🔁 Both paths render the same way (pdfjs-dist + canvas) and upload to the same R2 bucket, so a thumbnail produced by one is interchangeable with the other.

✨ Features

🖼️ PNG thumbnail generated from the first page of any PDF URL
☁️ Upload to Cloudflare R2 using the S3 API
🔐 Bearer-token API authentication
🛡️ Rate limiting (built-in Fastify plugin; Upstash on Vercel)
📚 Interactive Swagger/OpenAPI documentation (Fastify path)
💎 TypeScript end-to-end

🐎 Path A — Fastify (Hetzner / self-host)

📋 Prerequisites

Node.js 18+
PM2 (production)
Cloudflare R2 credentials

📦 Install

git clone <repository-url>
cd pdf-url-screenshot
npm install
cp env.example .env
# edit .env with your credentials
npm run build

▶️ Run

npm run dev              # dev mode
npm run pm2:start        # production with PM2
npm run pm2:logs         # tail logs
npm run pm2:restart      # restart after deploy

Server listens on PORT (default 3000).

🔧 Required environment

Variable	Notes
`API_KEYS`	Comma-separated bearer tokens (required)
`R2_ACCOUNT_ID`	Cloudflare R2 account ID
`R2_ACCESS_KEY_ID`	R2 access key
`R2_SECRET_ACCESS_KEY`	R2 secret key
`R2_MAIN_BUCKET_NAME`	R2 bucket name
`R2_PUBLIC_BUCKET_URL`	Public bucket URL, e.g. `https://media.example.com`
`PORT`	Server port (default `3000`)
`SERVER_URL`	Full server URL for Swagger (default `http://localhost:3000`)

🔑 Generating an API key

node -e "console.log('sk_live_' + require('crypto').randomBytes(32).toString('hex'))"

Add it to API_KEYS (comma-separated if multiple).

📚 Swagger UI

Once the server is running:

http://localhost:3000/docs

Click 🔒 Authorize, paste your API key, and try endpoints directly.

⚡ Path B — Vercel serverless

The Vercel implementation lives entirely under vercel/ and is self-contained (own package.json).

🛠️ One-time setup

cd vercel
npm install
npm i -g vercel          # if you don't have the CLI yet
vercel login
vercel link --yes --project pdf-screenshot

🔧 Configure environment

Required (preview + production scopes):

Variable	Notes
`API_KEYS`	Comma-separated bearer tokens
`R2_ACCOUNT_ID`	Cloudflare R2 account ID
`R2_ACCESS_KEY_ID`	R2 access key
`R2_SECRET_ACCESS_KEY`	R2 secret key
`R2_MAIN_BUCKET_NAME`	R2 bucket name
`R2_PUBLIC_BUCKET_URL`	Public bucket URL

Optional (rate limiting — function no-ops with a warning if unset):

Variable	Notes
`UPSTASH_REDIS_REST_URL`	Upstash Redis REST endpoint
`UPSTASH_REDIS_REST_TOKEN`	Upstash Redis REST token

Add each one interactively (value never enters shell history or LLM context):

vercel env add API_KEYS preview
vercel env add R2_ACCOUNT_ID preview
# …repeat for every variable above, then for `production` scope when ready

🚢 Deploy

npm run deploy           # preview deploy
npm run deploy:prod      # production deploy

🔒 Vercel "Deployment Protection": by default, preview URLs require Vercel SSO. Either disable it (Project Settings → Deployment Protection) before testing from external clients, or use vercel curl (the CLI handles SSO automatically).

🧪 Local validation without deploying

cd vercel
node scripts/smoke-render.mjs           # renderer-only sanity, no R2/Vercel needed
npx tsx scripts/smoke-handler.mjs       # handler guard-branch checks
npx tsc --noEmit                        # typecheck
npm run dev                             # `vercel dev` against linked project + env

🔌 API

Both deploy paths expose the same endpoint.

`POST /upload/pdf-screenshot` (Fastify) / `POST /api/upload/pdf-screenshot` (Vercel)

📨 Headers

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

📦 Body

{ "url": "https://example.com/document.pdf", "userId": "alice" }

✅ Success (200)

{
  "success": true,
  "path": "pdf_thumbnails/alice/thumb-document.png",
  "publicUrl": "https://media.example.com/pdf_thumbnails/alice/thumb-document.png"
}

❌ Errors

Code	Meaning
`400`	Invalid request body or PDF could not be fetched
`401`	Missing or invalid bearer token
`429`	Rate limit exceeded
`500`	Render or upload failure (details in body)

🌀 Curl

Fastify:

curl -X POST http://localhost:3000/upload/pdf-screenshot \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/document.pdf","userId":"alice"}'

Vercel:

curl -X POST https://<your-deployment>.vercel.app/api/upload/pdf-screenshot \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/document.pdf","userId":"alice"}'

🛡️ Rate limiting

🐎 Fastify (Hetzner) — @fastify/rate-limit. Global: 100 req/min/IP. PDF endpoint: 10 req/hour/IP. Localhost is whitelisted.
⚡ Vercel — @upstash/ratelimit against Upstash Redis. Global: 100 req/min/IP. PDF endpoint: 10 req/min/IP. If Upstash env vars are unset, the limiter logs a warning and allows all traffic.

Rate-limit headers (x-ratelimit-limit, x-ratelimit-remaining, x-ratelimit-reset) are present on the Fastify path.

🗂️ Project structure

pdf-url-screenshot/
├── index.ts                 # Fastify entry
├── routes/                  # Fastify route handlers
│   ├── root.ts
│   └── upload/
│       └── pdf-screenshot.ts
├── schemas/                 # Shared response schemas
├── r2Client.ts              # S3-API client for R2
├── env.schema.ts            # Env validation (Fastify)
├── swagger.config.ts        # OpenAPI + Swagger UI config
├── rate-limit.config.ts     # Rate limit config (Fastify)
├── types.ts
├── ecosystem.config.js      # PM2 config
├── tsconfig.json
├── package.json
│
├── vercel/                  # Vercel serverless implementation
│   ├── api/
│   │   ├── upload/pdf-screenshot.ts    # handler (default export)
│   │   └── _lib/
│   │       ├── pdf-render.ts           # pdfjs-dist + canvas renderer
│   │       ├── r2-upload.ts            # S3 client wrapper
│   │       ├── auth.ts                 # bearer token check
│   │       ├── rate-limit.ts           # Upstash-backed limiter
│   │       └── schemas.ts              # zod schemas
│   ├── scripts/             # smoke tests (renderer, handler)
│   ├── package.json
│   ├── vercel.json
│   ├── tsconfig.json
│   └── .env.example
│
└── docs/
    └── serverless-migration.md         # detailed log of the move to Vercel

⚙️ Technical details

🖼️ PDF rendering

pdfjs-dist 3.4.120 (legacy build) + canvas 3.2.0 (Cairo).
Renders page 1 at 1.5× scale by default.
Output is a PNG buffer.

📦 Storage

Cloudflare R2 via AWS S3 SDK (@aws-sdk/client-s3).
Object key shape: pdf_thumbnails/{userId}/thumb-{filename}.png.
Public URL returned in the response.

🩺 Troubleshooting

🐎 Fastify (Hetzner)

npm run pm2:status     # check process state
npm run pm2:logs       # tail live logs
npm run pm2:restart    # restart after deploy
npm run pm2:delete && npm run build && npm run pm2:start   # full reset

⚡ Vercel

vercel ls                                       # list recent deployments
vercel inspect --logs <deployment-url>          # build logs
vercel logs <deployment-url> --json             # runtime logs
vercel curl "<deployment-url>/api/..." -- ...   # auth-aware curl through deployment protection

📖 For the full history of how the Vercel path was put together (what broke, what got pinned, why we ended up on Node 22 + canvas instead of other combos), see docs/serverless-migration.md.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

📄 PDF Screenshot Service

🚀 Deployment options

✨ Features

🐎 Path A — Fastify (Hetzner / self-host)

📋 Prerequisites

📦 Install

▶️ Run

🔧 Required environment

🔑 Generating an API key

📚 Swagger UI

⚡ Path B — Vercel serverless

🛠️ One-time setup

🔧 Configure environment

🚢 Deploy

🧪 Local validation without deploying

🔌 API

`POST /upload/pdf-screenshot` (Fastify) / `POST /api/upload/pdf-screenshot` (Vercel)

🌀 Curl

🛡️ Rate limiting

🗂️ Project structure

⚙️ Technical details

🖼️ PDF rendering

📦 Storage

🩺 Troubleshooting

🐎 Fastify (Hetzner)

⚡ Vercel

About

Uh oh!

Releases

Packages

Uh oh!

Contributors

Uh oh!

Languages

Name		Name	Last commit message	Last commit date
Latest commit History 14 Commits
docs		docs
routes		routes
schemas		schemas
vercel		vercel
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
RATE_LIMITING.md		RATE_LIMITING.md
README.md		README.md
ecosystem.config.js		ecosystem.config.js
env.example		env.example
env.schema.ts		env.schema.ts
index.ts		index.ts
package.json		package.json
r2Client.ts		r2Client.ts
rate-limit.config.ts		rate-limit.config.ts
swagger.config.ts		swagger.config.ts
tsconfig.json		tsconfig.json
types.ts		types.ts

Folders and files

Latest commit

History

Repository files navigation

📄 PDF Screenshot Service

🚀 Deployment options

✨ Features

🐎 Path A — Fastify (Hetzner / self-host)

📋 Prerequisites

📦 Install

▶️ Run

🔧 Required environment

🔑 Generating an API key

📚 Swagger UI

⚡ Path B — Vercel serverless

🛠️ One-time setup

🔧 Configure environment

🚢 Deploy

🧪 Local validation without deploying

🔌 API

POST /upload/pdf-screenshot (Fastify) / POST /api/upload/pdf-screenshot (Vercel)

🌀 Curl

🛡️ Rate limiting

🗂️ Project structure

⚙️ Technical details

🖼️ PDF rendering

📦 Storage

🩺 Troubleshooting

🐎 Fastify (Hetzner)

⚡ Vercel

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

`POST /upload/pdf-screenshot` (Fastify) / `POST /api/upload/pdf-screenshot` (Vercel)

Packages