prerender: allow handlers to skip a route at runtime

Describe the feature

A handler should be able to tell the prerenderer "don't write this route, it's served at runtime" while it handles the prerender request.

Use case: the app only learns which routes are dynamic when it handles them, e.g. a content-driven site where a page's frontmatter says prerender: false. With crawlLinks: true, links to those routes are found and fetched, and the handler knows (via import.meta.prerender / the x-nitro-prerender request header) that it's being prerendered, but it has no clean way to opt out.

What happens today (v3 prerender()):

• Status other than 200/3xx → route.error → added to failedRoutes → fails the build with failOnError: true. With failOnError: false it is effectively skipped, but real errors are no longer caught.
• 3xx → accepted and written to disk.
• The x-nitro-prerender response header can only add routes.
• prerender:generate can set route.skip, but the route object has no response headers (only contentType), so a handler signal can't reach it without hacks.

The only way left is duplicating the "which routes are dynamic" logic at build time in prerender:routes + prerender.ignore, which often means loading app data twice (once in the builder, once in the prerender worker).

Possible API (any would work):

1. A response header, e.g. x-nitro-prerender: false, or a dedicated x-nitro-prerender-skip: 1: the route is marked skipped (not failed), nothing is written, and its links are not crawled.
2. Expose the response headers on the route object in prerender:generate, so a hook can set route.skip from them.

(1) is simplest for handlers:

export default defineEventHandler((event) => {
  if (import.meta.prerender && isDynamic(event)) {
    return new Response(null, { status: 204, headers: { "x-nitro-prerender": "false" } });
  }
  // ...
});

Skipped routes should probably be logged like ignored ones and kept out of failedRoutes.

Additional information

• Would you be willing to help implement this feature?

[!NOTE] This issue was drafted with an AI assistant and reviewed before posting.

Generated with AI assistant