Getting started

Requirements

• Node.js 20 or newer
• A platform Puppeteer supports (Linux, macOS, Windows). On install, Puppeteer downloads a compatible Chromium build (~150 MB).

Install

npm

npm install headless-prerender

pnpm

pnpm add headless-prerender

yarn

yarn add headless-prerender

To run it without adding it to a project:

npx headless-prerender serve

Using a system Chromium

If you do not want Puppeteer's bundled browser, set the executable path:

export PUPPETEER_EXECUTABLE_PATH=/usr/bin/chromium
# or pass it per invocation:
headless-prerender serve --executable-path /usr/bin/chromium

To skip the Chromium download entirely during install:

PUPPETEER_SKIP_DOWNLOAD=1 npm install headless-prerender

Run the server

headless-prerender serve --port 3000

Then request the rendered HTML of any page:

curl "http://localhost:3000/render?url=https://your-app.com/some/page"

The response is the fully-rendered HTML document, with:

Header	Meaning
x-prerender-cache	hit or miss
x-prerender-duration-ms	Render time in milliseconds (on a miss)

A health check is available at GET /health.

Render a single page

For one-off use or scripting:

headless-prerender render https://your-app.com/page --out page.html

Use it as a library

import { Renderer } from "headless-prerender";

const renderer = new Renderer({ extraWaitMs: 300 });

const { html, status, url, durationMs } = await renderer.render(
  "https://your-app.com/page",
);

console.log(status, url, durationMs);

await renderer.close();

Next steps

• Put it behind a reverse proxy so bots are routed to it automatically.
• Enable caching to cut repeated render cost.
• Lock it down before exposing it to the internet.
• Follow a framework guide: React, Vue, Angular, Next.js.