headless-prerender

Prerender / dynamic-rendering service for JavaScript single-page apps (React, Vue, Angular, Svelte, Next.js). It renders your app with headless Chromium, waits for client-side rendering to finish, and returns fully-rendered static HTML to crawlers, SEO bots and social-media scrapers.

Ships as both a library and a CLI in one npm package.

Documentation: https://headless-prerender.netlify.app/

Why

A single-page app ships an almost-empty document and builds the page in the browser with JavaScript. Crawlers and scrapers that do not execute JavaScript (many search engines, and every major social preview bot) see only an empty root element - no headings, no text, no links, no meta tags.

headless-prerender sits between your app and those bots: it loads the page in a real browser, captures the rendered HTML, and serves that instead. Human visitors are unaffected and still get the normal SPA.

See What is prerendering? for the full picture, including when SSR is the better choice.

Install

npm install headless-prerender
# or, without adding it to a project:
npx headless-prerender serve

Requires Node.js 20+. On install, Puppeteer downloads a compatible Chromium (~150 MB). To use a system browser instead:

export PUPPETEER_EXECUTABLE_PATH=/usr/bin/chromium

Quick start

As a service

headless-prerender serve --port 3000 --cache-ttl 300000

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

The response is the fully-rendered HTML, with x-prerender-cache and x-prerender-duration-ms headers. A health check lives at GET /health.

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",
);

await renderer.close();

Or run the server programmatically:

import { PrerenderServer } from "headless-prerender";

const server = new PrerenderServer({
  cacheTtlMs: 300_000,
  token: process.env.PRERENDER_TOKEN,
  allowedOrigins: ["https://your-app.com"],
});

await server.listen();

Production setup

You do not expose the service directly. Your reverse proxy or CDN detects bot traffic and forwards only those requests to headless-prerender:

Bot request ──▶ reverse proxy ──(is a crawler?)──▶ headless-prerender ──▶ rendered HTML
                                └─(otherwise)─────▶ your static files / CDN

Ready-to-use recipes for Nginx, Cloudflare Workers and Apache are in Reverse-proxy setup.

Framework guides

| Framework | Guide | | --- | --- | | React (CRA, Vite, React Router) | /frameworks/react | | Vue (Vue Router, history mode) | /frameworks/vue | | Angular (client-side, no Universal) | /frameworks/angular | | Next.js (static export, client-only routes) | /frameworks/nextjs |

CLI

headless-prerender serve [options]           Start the prerender HTTP server
headless-prerender render <url> [options]    Render one URL and print/save HTML

| Common option | Default | Description | | --- | --- | --- | | --timeout <ms> | 20000 | Navigation timeout | | --wait-until <event> | networkidle2 | load / domcontentloaded / networkidle0 / networkidle2 | | --extra-wait <ms> | 0 | Extra settle time after load | | --user-agent <string> | Mozilla/5.0 (compatible; headless-prerender) | UA sent to the page | | --allow-origin <origin> | none | Restrict rendering to this origin (repeatable) | | --executable-path <path> | bundled Chromium | Path to a Chromium binary |

| serve option | Default | Description | | --- | --- | --- | | --port <n> | 3000 | Port to listen on | | --host <host> | 0.0.0.0 | Interface to bind | | --cache-ttl <ms> | 0 | In-memory cache TTL (0 = off) | | --token <string> | none | Require this token on requests |

Full reference: CLI.

API

new Renderer(options?)

| Method | Description | | --- | --- | | render(url): Promise<RenderResult> | Render one URL to HTML | | close(): Promise<void> | Close the browser (always call when done) |

RenderResult is { html, status, url, durationMs }.

new PrerenderServer(options?)

| Method | Description | | --- | --- | | listen(): Promise<number> | Start listening; resolves with the bound port | | close(): Promise<void> | Stop the server and close the browser |

Options and return types: API reference.

Configuration

| Option | Default | Description | | --- | --- | --- | | timeout | 20000 | Navigation timeout (ms) | | waitUntil | "networkidle2" | Readiness condition | | extraWaitMs | 0 | Extra settle time after load | | userAgent | Mozilla/5.0 (compatible; headless-prerender) | UA sent to the page | | width / height | 1280 / 800 | Viewport size | | blockResourceTypes | ["image", "media", "font"] | Request types to abort during render | | allowedOrigins | [] | Restrict rendering to these origins | | executablePath | bundled Chromium | Path to a Chromium binary | | launchArgs | [] | Extra Chromium flags |

PrerenderServer also accepts port, host, cacheTtlMs, token.

Security

An unprotected instance is an SSRF proxy. Before exposing it:

• Set allowedOrigins to your site's origins.
• Set a token and require it at the proxy.
• Bind to localhost / a private network; do not publish the port.
• Run it in a container with memory and CPU limits.

Details: Security.

Docker

A Dockerfile based on Puppeteer's official image is included. See Docker.

Development

npm install
npm run build
npm test          # renders a local page with real Chromium
npm run docs:dev  # run the documentation site locally

Publishing note

If the unscoped name headless-prerender is unavailable on npm, publish under a scope (for example @your-username/headless-prerender) by changing the name field in package.json and running npm publish --access public.

License

MIT