Next.js

Most Next.js apps do not need headless-prerender - the App Router and Pages Router already render HTML on the server or at build time, so crawlers get full markup.

Reach for prerendering only in these cases.

When it helps

1. A statically exported, client-heavy app

With output: "export" you ship static HTML, but any content rendered only in useEffect (client-side data fetching, next/dynamic with ssr: false) is missing from that HTML. Prerendering fills it in.

2. Client-only pages inside an otherwise SSR app

Pages that opt out of SSR ("use client" components that fetch on mount, widgets that only run in the browser) can be prerendered for bots while the rest of the app is served normally.

3. Reliable social previews for dynamic OG data

If Open Graph tags depend on client-side data, prerendering captures the final <head>. (Prefer the Next.js Metadata API or generateMetadata when you can.)

Setup

1. Deploy your Next.js app as normal.

2. Run the service, allowing your origin:

   headless-prerender serve \
     --port 3000 \
     --allow-origin https://www.example.com \
     --cache-ttl 600000

3. Route bot traffic for the affected routes only - you do not need to prerender pages that Next.js already renders server-side.

Scoping the proxy to client-only routes

In your reverse proxy, restrict the prerender rewrite to the path prefixes that are client-rendered, e.g.:

location /app/ {
    if ($is_bot = 1) { rewrite ^ /_prerender last; }
    try_files $uri /index.html;
}

Leave all other routes going straight to Next.js.

Checklist

• [ ] Confirmed the route is actually client-rendered (view source, no content)
• [ ] Proxy rewrite scoped to those routes only
• [ ] --allow-origin set
• [ ] --extra-wait tuned if data loads late
• [ ] Caching enabled with a generous TTL