PrerenderServer

An HTTP server that renders pages on request.

import { PrerenderServer } from "headless-prerender";

Constructor

new PrerenderServer(options?: ServerOptions)

Creates the server without starting it. ServerOptions extends RendererOptions with server-specific fields:

Option	Type	Default	Description
port	number	3000	TCP port to listen on
host	string	"0.0.0.0"	Interface to bind
cacheTtlMs	number	0	In-memory cache TTL; 0 disables caching
token	string	none	Required token, via ?token= or x-prerender-token

const server = new PrerenderServer({
  port: 3000,
  host: "127.0.0.1",
  cacheTtlMs: 300_000,
  token: process.env.PRERENDER_TOKEN,
  allowedOrigins: ["https://www.example.com"],
});

listen()

listen(): Promise<number>

Starts listening and resolves with the bound port (useful when port is 0).

const port = await server.listen();
console.log(`Listening on ${port}`);

close()

close(): Promise<void>

Stops accepting connections and closes the browser. Resolves when both are done.

process.on("SIGTERM", () => server.close().then(() => process.exit(0)));

HTTP API

GET /render

Query param	Required	Description
url	yes	Absolute http(s) URL to render
token	only if a token is configured	The access token

Response: the rendered HTML document.

Response header	Description
x-prerender-cache	hit or miss
x-prerender-duration-ms	Render time in ms (on a miss)

Status	When
200 and the page's own status	Success (the upstream status is passed through)
400	Missing url parameter
401	Token configured and missing/incorrect
404	Any path other than /render or /health
500	Render error (invalid URL, disallowed origin, navigation failure)

GET /health

Returns 200 with body {"ok":true}. No token required.

Example

import { PrerenderServer } from "headless-prerender";

const server = new PrerenderServer({
  cacheTtlMs: 60_000,
  token: process.env.PRERENDER_TOKEN,
  allowedOrigins: ["https://www.example.com"],
});

const port = await server.listen();
console.log(`headless-prerender on :${port}`);

for (const sig of ["SIGINT", "SIGTERM"] as const) {
  process.on(sig, () => server.close().then(() => process.exit(0)));
}