Renderer

Renders JavaScript-heavy pages to static HTML using a single, reused headless Chromium instance.

import { Renderer } from "headless-prerender";

Constructor

new Renderer(options?: RendererOptions)

Creates a renderer. The browser is not launched yet - it starts lazily on the first render() call and is then reused for every subsequent call.

See Options for the full RendererOptions shape.

const renderer = new Renderer({
  timeout: 30_000,
  waitUntil: "networkidle0",
  extraWaitMs: 300,
  allowedOrigins: ["https://www.example.com"],
});

render(url)

render(url: string): Promise<RenderResult>

Renders a single URL and resolves with the fully-rendered HTML.

Parameters

Name	Type	Description
url	string	Absolute http(s) URL to render

Returns RenderResult

Field	Type	Description
html	string	The final, fully-rendered HTML document
status	number	HTTP status of the top-level navigation (0 if unknown)
url	string	The URL after any redirects
durationMs	number	Wall-clock render time in milliseconds

Throws

Message	Cause
Invalid URL: ...	The string is not a valid URL
Unsupported protocol: ...	Not http: or https:
Origin not allowed: ...	allowedOrigins is set and does not include this origin
Puppeteer navigation errors	Timeout, DNS failure, connection refused, etc.

Example

const { html, status, url, durationMs } = await renderer.render(
  "https://www.example.com/products/42",
);

if (status >= 400) {
  console.warn(`Upstream returned ${status}`);
}

close()

close(): Promise<void>

Closes the underlying browser. Safe to call more than once, and safe to call before any render(). After closing, the next render() launches a fresh browser.

Always call this when you are done, or the Node process will not exit:

const renderer = new Renderer();
try {
  await renderer.render("https://www.example.com");
} finally {
  await renderer.close();
}

Concurrency

Each render() opens its own browser page (tab) in the shared browser, so concurrent calls are supported:

const renderer = new Renderer();
const [a, b] = await Promise.all([
  renderer.render("https://www.example.com/a"),
  renderer.render("https://www.example.com/b"),
]);
await renderer.close();

Each open page costs memory. For high concurrency, cap the number of in-flight render() calls yourself (a queue or a semaphore) and monitor memory.