@trimbex/ghost-pdf

Local ghost-client PDF API: runs headless Chromium, opens a page from your web app, returns a consistent landscape PDF.

Friend quick start

1. Start your web app

Whatever you normally use (npm run dev, etc.). Note the origin (e.g. http://localhost:5173).

2. Start the PDF API (another terminal)

PowerShell:

$env:APP_URL = "http://localhost:5173"
$env:PORT = "3000"
npx @trimbex/ghost-pdf

cmd / bash:

set APP_URL=http://localhost:5173
set PORT=3000
npx @trimbex/ghost-pdf

Or with npm scripts after install:

npm install -D @trimbex/ghost-pdf

{
  "scripts": {
    "pdf-api": "cross-env APP_URL=http://localhost:5173 PORT=3000 ghost-pdf"
  }
}

First run downloads Chromium (one-time, needs network).

3. Call it from your app

async function downloadPdf(path) {
  const res = await fetch('http://localhost:3000/generate-pdf', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      path, // e.g. '/invoice/42'
      query: { print: '1' },
    }),
  });
  if (!res.ok) throw new Error(await res.text());
  const blob = await res.blob();
  const url = URL.createObjectURL(blob);
  window.open(url); // or trigger a download
}

4. Smoke test

curl http://localhost:3000/health

curl -X POST http://localhost:3000/generate-pdf ^
  -H "Content-Type: application/json" ^
  -d "{\"path\":\"/\",\"query\":{\"print\":\"1\"}}" ^
  --output test.pdf

App tips (print-friendly pages)

• Honor ?print=1 to hide nav / chrome (the API always appends print=1).
• Wrap blocks that should not split across pages in .pdf-keep-together.
• PDFs always use a desktop 1440×900 viewport, regardless of the caller's device.

API

GET /health

{ "ok": true, "appUrl": "http://localhost:5173", "allowedPages": null }

POST /generate-pdf

{ "path": "/reports/123", "query": { "print": "1" } }

Also accepts { "page": "dashboard" } (becomes /dashboard).

Response: application/pdf

Environment

| Variable | Default | Purpose | |----------|---------|---------| | APP_URL | http://localhost:5173 | Base URL Chromium opens | | VUE_APP_URL | — | Legacy alias for APP_URL | | PORT | 3000 | API listen port | | PDF_ALLOWED_PAGES | (empty = all) | Optional comma list of first path segments | | PUPPETEER_EXECUTABLE_PATH | — | Optional system Chrome path |

Security note

This is meant for local / trusted use. Paths are relative to APP_URL only (no arbitrary remote URLs).