feat: configure error reporting for prerendered routes (#11702)

* feat: configure error reporting when routes marked as prerendable were not prerendered

* tweak wording, update links

* lint

* lint

* Update packages/kit/src/exports/public.d.ts

Co-authored-by: Ben McCann <[email protected]>

* Update packages/kit/types/index.d.ts

* Update packages/kit/types/index.d.ts

* Update packages/kit/src/exports/public.d.ts

* rename to handleUnseenRoutes

* tweak message

---------

Co-authored-by: Simon H <[email protected]>
Co-authored-by: Tee Ming <[email protected]>
Co-authored-by: Ben McCann <[email protected]>
Co-authored-by: Rich Harris <[email protected]>

Author: 5 people

.changeset/gentle-llamas-yawn.md

@@ -0,0 +1,5 @@
+---
+"@sveltejs/kit": minor
+---
+
+feat: configure error reporting when routes marked as prerendable were not prerendered

packages/kit/src/core/config/options.js

@@ -251,6 +251,20 @@ const options = object(
 					}
 				),
 
+				handleUnseenRoutes: validate(
+					(/** @type {any} */ { message }) => {
+						throw new Error(
+							message +
+								'\nTo suppress or handle this error, implement `handleUnseenRoutes` in https://svelte.dev/docs/kit/configuration#prerender'
+						);
+					},
+					(input, keypath) => {
+						if (typeof input === 'function') return input;
+						if (['fail', 'warn', 'ignore'].includes(input)) return input;
+						throw new Error(`${keypath} should be "fail", "warn", "ignore" or a custom function`);
+					}
+				),
+
 				origin: validate('http://sveltekit-prerender', (input, keypath) => {
 					assert_string(input, keypath);
 

packages/kit/src/core/postbuild/prerender.js

@@ -160,6 +160,15 @@ async function prerender({ hash, out, manifest_path, metadata, verbose, env }) {
 		}
 	);
 
+	const handle_not_prerendered_route = normalise_error_handler(
+		log,
+		config.prerender.handleUnseenRoutes,
+		({ routes }) => {
+			const list = routes.map((id) => `  - ${id}`).join('\n');
+			return `The following routes were marked as prerenderable, but were not prerendered because they were not found while crawling your app:\n${list}\n\nSee the \`handleUnseenRoutes\` option in https://svelte.dev/docs/kit/configuration#prerender for more info.`;
+		}
+	);
+
 	const q = queue(config.prerender.concurrency);
 
 	/**
@@ -562,11 +571,7 @@ async function prerender({ hash, out, manifest_path, metadata, verbose, env }) {
 	}
 
 	if (not_prerendered.length > 0) {
-		const list = not_prerendered.map((id) => `  - ${id}`).join('\n');
-
-		throw new Error(
-			`The following routes were marked as prerenderable, but were not prerendered because they were not found while crawling your app:\n${list}\n\nSee https://svelte.dev/docs/kit/page-options#prerender-troubleshooting for info on how to solve this`
-		);
+		handle_not_prerendered_route({ routes: not_prerendered });
 	}
 
 	return { prerendered, prerender_map };

packages/kit/src/exports/public.d.ts

@@ -12,6 +12,7 @@ import {
 	PrerenderEntryGeneratorMismatchHandlerValue,
 	PrerenderHttpErrorHandlerValue,
 	PrerenderMissingIdHandlerValue,
+	PrerenderMissingRoutesHandlerValue,
 	PrerenderOption,
 	RequestOptions,
 	RouteSegment
@@ -740,6 +741,21 @@ export interface KitConfig {
 		 * @since 1.16.0
 		 */
 		handleEntryGeneratorMismatch?: PrerenderEntryGeneratorMismatchHandlerValue;
+		/**
+		 * How to respond when a route is marked as prerenderable but has not been prerendered.
+		 *
+		 * - `'fail'` — fail the build
+		 * - `'ignore'` - silently ignore the failure and continue
+		 * - `'warn'` — continue, but print a warning
+		 * - `(details) => void` — a custom error handler that takes a `details` object with a `routes` property which contains all routes that haven't been prerendered. If you `throw` from this function, the build will fail
+		 *
+		 * The default behavior is to fail the build. This may be undesirable when you know that some of your routes may never be reached under certain
+		 * circumstances such as a CMS not returning data for a specific area, resulting in certain routes never being reached.
+		 *
+		 * @default "fail"
+		 * @since 2.16.0
+		 */
+		handleUnseenRoutes?: PrerenderMissingRoutesHandlerValue;
 		/**
 		 * The value of `url.origin` during prerendering; useful if it is included in rendered content.
 		 * @default "http://sveltekit-prerender"

packages/kit/src/types/private.d.ts

@@ -208,8 +208,17 @@ export interface PrerenderEntryGeneratorMismatchHandler {
 	(details: { generatedFromId: string; entry: string; matchedId: string; message: string }): void;
 }
 
+export interface PrerenderEntryMissingRoutesHandler {
+	(details: { routes: string[]; message: string }): void;
+}
+
 export type PrerenderHttpErrorHandlerValue = 'fail' | 'warn' | 'ignore' | PrerenderHttpErrorHandler;
 export type PrerenderMissingIdHandlerValue = 'fail' | 'warn' | 'ignore' | PrerenderMissingIdHandler;
+export type PrerenderMissingRoutesHandlerValue =
+	| 'fail'
+	| 'warn'
+	| 'ignore'
+	| PrerenderEntryMissingRoutesHandler;
 export type PrerenderEntryGeneratorMismatchHandlerValue =
 	| 'fail'
 	| 'warn'

packages/kit/types/index.d.ts

@@ -717,6 +717,21 @@ declare module '@sveltejs/kit' {
 			 * @since 1.16.0
 			 */
 			handleEntryGeneratorMismatch?: PrerenderEntryGeneratorMismatchHandlerValue;
+			/**
+			 * How to respond when a route is marked as prerenderable but has not been prerendered.
+			 *
+			 * - `'fail'` — fail the build
+			 * - `'ignore'` - silently ignore the failure and continue
+			 * - `'warn'` — continue, but print a warning
+			 * - `(details) => void` — a custom error handler that takes a `details` object with a `routes` property which contains all routes that haven't been prerendered. If you `throw` from this function, the build will fail
+			 *
+			 * The default behavior is to fail the build. This may be undesirable when you know that some of your routes may never be reached under certain
+			 * circumstances such as a CMS not returning data for a specific area, resulting in certain routes never being reached.
+			 *
+			 * @default "fail"
+			 * @since 2.16.0
+			 */
+			handleUnseenRoutes?: PrerenderMissingRoutesHandlerValue;
 			/**
 			 * The value of `url.origin` during prerendering; useful if it is included in rendered content.
 			 * @default "http://sveltekit-prerender"
@@ -1996,8 +2011,17 @@ declare module '@sveltejs/kit' {
 		(details: { generatedFromId: string; entry: string; matchedId: string; message: string }): void;
 	}
 
+	interface PrerenderEntryMissingRoutesHandler {
+		(details: { routes: string[]; message: string }): void;
+	}
+
 	type PrerenderHttpErrorHandlerValue = 'fail' | 'warn' | 'ignore' | PrerenderHttpErrorHandler;
 	type PrerenderMissingIdHandlerValue = 'fail' | 'warn' | 'ignore' | PrerenderMissingIdHandler;
+	type PrerenderMissingRoutesHandlerValue =
+		| 'fail'
+		| 'warn'
+		| 'ignore'
+		| PrerenderEntryMissingRoutesHandler;
 	type PrerenderEntryGeneratorMismatchHandlerValue =
 		| 'fail'
 		| 'warn'