improve an error message for getstaticpaths (#4153)

.changeset/pretty-bananas-refuse.md

@@ -0,0 +1,5 @@
+---
+'astro': patch
+---
+
+Improve an error message for getStaticPaths

packages/astro/src/core/render/route-cache.ts

@@ -9,10 +9,7 @@ import type {
 import { debug, LogOptions, warn } from '../logger/core.js';
 
 import { stringifyParams } from '../routing/params.js';
-import {
+import { validateDynamicRouteModule, validateGetStaticPathsResult } from '../routing/validation.js';
-	validateGetStaticPathsModule,
-	validateGetStaticPathsResult,
-} from '../routing/validation.js';
 import { generatePaginateFunction } from './paginate.js';
 
 interface CallGetStaticPathsOptions {
@@ -30,21 +27,28 @@ export async function callGetStaticPaths({
 	route,
 	ssr,
 }: CallGetStaticPathsOptions): Promise<RouteCacheEntry> {
-	validateGetStaticPathsModule(mod, { ssr });
+	validateDynamicRouteModule(mod, { ssr, logging });
-
+	// No static paths in SSR mode. Return an empty RouteCacheEntry.
-	let staticPaths: GetStaticPathsResult = [];
+	if (ssr) {
-	if (mod.getStaticPaths) {
+		return { staticPaths: Object.assign([], { keyed: new Map() }) };
-		staticPaths = (
-			await mod.getStaticPaths({
-				paginate: generatePaginateFunction(route),
-				rss() {
-					throw new Error(
-						'The RSS helper has been removed from getStaticPaths! Try the new @astrojs/rss package instead. See https://docs.astro.build/en/guides/rss/'
-					);
-				},
-			})
-		).flat();
 	}
+	// Add a check here to my TypeScript happy.
+	// This is already checked in validateDynamicRouteModule().
+	if (!mod.getStaticPaths) {
+		throw new Error('Unexpected Error.');
+	}
+	// Calculate your static paths.
+	let staticPaths: GetStaticPathsResult = [];
+	staticPaths = (
+		await mod.getStaticPaths({
+			paginate: generatePaginateFunction(route),
+			rss() {
+				throw new Error(
+					'The RSS helper has been removed from getStaticPaths! Try the new @astrojs/rss package instead. See https://docs.astro.build/en/guides/rss/'
+				);
+			},
+		})
+	).flat();
 
 	const keyedStaticPaths = staticPaths as GetStaticPathsResultKeyed;
 	keyedStaticPaths.keyed = new Map<string, GetStaticPathsItem>();

packages/astro/src/core/routing/index.ts

@@ -2,4 +2,4 @@ export { createRouteManifest } from './manifest/create.js';
 export { deserializeRouteData, serializeRouteData } from './manifest/serialization.js';
 export { matchAllRoutes, matchRoute } from './match.js';
 export { getParams } from './params.js';
-export { validateGetStaticPathsModule, validateGetStaticPathsResult } from './validation.js';
+export { validateDynamicRouteModule, validateGetStaticPathsResult } from './validation.js';

packages/astro/src/core/routing/validation.ts

@@ -4,10 +4,6 @@ import { warn } from '../logger/core.js';
 
 const VALID_PARAM_TYPES = ['string', 'number', 'undefined'];
 
-interface ValidationOptions {
-	ssr: boolean;
-}
-
 /** Throws error for invalid parameter in getStaticPaths() response */
 export function validateGetStaticPathsParameter([key, value]: [string, any]) {
 	if (!VALID_PARAM_TYPES.includes(typeof value)) {
@@ -17,14 +13,28 @@ export function validateGetStaticPathsParameter([key, value]: [string, any]) {
 	}
 }
 
-/** Throw error for deprecated/malformed APIs */
+/** Warn or error for deprecated or malformed route components */
-export function validateGetStaticPathsModule(mod: ComponentInstance, { ssr }: ValidationOptions) {
+export function validateDynamicRouteModule(
+	mod: ComponentInstance,
+	{
+		ssr,
+		logging,
+	}: {
+		ssr: boolean;
+		logging: LogOptions;
+	}
+) {
 	if ((mod as any).createCollection) {
 		throw new Error(`[createCollection] deprecated. Please use getStaticPaths() instead.`);
 	}
-	if (!mod.getStaticPaths && !ssr) {
+	if (ssr && mod.getStaticPaths) {
+		warn(logging, 'getStaticPaths', 'getStaticPaths() is ignored when "output: server" is set.');
+	}
+	if (!ssr && !mod.getStaticPaths) {
 		throw new Error(
-			`[getStaticPaths] getStaticPaths() function is required. Make sure that you \`export\` the function from your component.`
+			`[getStaticPaths] getStaticPaths() function is required.
+Make sure that you \`export\` a \`getStaticPaths\` function from your dynamic route.
+Alternatively, set \`output: "server"\` in your Astro config file to switch to a non-static server build. `
 		);
 	}
 }