feat(next): astro:routes:resolved

.changeset/giant-ravens-look.md

@@ -0,0 +1,43 @@
+---
+'astro': minor
+---
+
+Adds a new `astro:routes:resolved` hook to the Integration API, and deprecates `routes` passed to `astro:build:done`
+
+When building an integration, you can now get access to routes inside the `astro:routes:resolved` hook:
+
+```js
+const integration = () => {
+    return {
+        name: 'my-integration',
+        hooks: {
+            'astro:routes:resolved': ({ routes }) => {
+                console.log(routes)
+            }
+        }
+    }
+}
+```
+
+This hook runs before `astro:config:done`, and whenever a route changes in development.
+
+`routes` from `astro:build:done` is now deprecated. We recommend you use the new hook instead:
+
+```diff
+const integration = () => {
++    let routes
+    return {
+        name: 'my-integration',
+        hooks: {
++            'astro:routes:resolved': (params) => {
++                routes = params.routes
++            },
+            'astro:build:done': ({
+-                routes
+            }) => {
+                console.log(routes)
+            }
+        }
+    }
+}
+```

packages/astro/src/actions/integration.ts

@@ -18,10 +18,11 @@ export default function astroIntegrationActionsRouteHandler({
 		name: VIRTUAL_MODULE_ID,
 		hooks: {
 			async 'astro:config:setup'(params) {
-				params.injectRoute({
+				settings.injectedRoutes.push({
 					pattern: '/_actions/[...path]',
 					entrypoint: 'astro/actions/runtime/route.js',
 					prerender: false,
+					origin: 'core',
 				});
 
 				params.addMiddleware({

packages/astro/src/assets/endpoint/config.ts

@@ -63,5 +63,6 @@ function getImageEndpointData(
 		pathname: settings.config.image.endpoint.route,
 		prerender: false,
 		fallbackRoutes: [],
+		origin: 'core',
 	};
 }

packages/astro/src/container/index.ts

@@ -544,6 +544,7 @@ export class experimental_AstroContainer {
 			type,
 			fallbackRoutes: [],
 			isIndex: false,
+			origin: 'user',
 		};
 	}
 

packages/astro/src/core/routing/astro-designed-error-pages.ts

@@ -15,6 +15,7 @@ export const DEFAULT_404_ROUTE: RouteData = {
 	route: '/404',
 	fallbackRoutes: [],
 	isIndex: false,
+	origin: 'core',
 };
 
 export const DEFAULT_500_ROUTE: RouteData = {
@@ -29,6 +30,7 @@ export const DEFAULT_500_ROUTE: RouteData = {
 	route: '/500',
 	fallbackRoutes: [],
 	isIndex: false,
+	origin: 'core',
 };
 
 export function ensure404Route(manifest: ManifestData) {

packages/astro/src/core/routing/manifest/create.ts

@@ -20,6 +20,7 @@ import { routeComparator } from '../priority.js';
 import { getRouteGenerator } from './generator.js';
 import { getPattern } from './pattern.js';
 import { getRoutePrerenderOption } from './prerender.js';
+import { runHookRoutesResolved } from '../../../integrations/hooks.js';
 const require = createRequire(import.meta.url);
 
 interface Item {
@@ -255,6 +256,7 @@ function createFileBasedRoutes(
 					prerender,
 					fallbackRoutes: [],
 					distURL: [],
+					origin: 'user',
 				});
 			}
 		}
@@ -280,7 +282,7 @@ function createInjectedRoutes({ settings, cwd }: CreateRouteManifestParams): Rou
 	const routes: RouteData[] = [];
 
 	for (const injectedRoute of settings.injectedRoutes) {
-		const { pattern: name, entrypoint, prerender: prerenderInjected } = injectedRoute;
+		const { pattern: name, entrypoint, prerender: prerenderInjected, origin } = injectedRoute;
 		const { resolved, component } = resolveInjectedRoute(entrypoint.toString(), config.root, cwd);
 
 		const segments = removeLeadingForwardSlash(name)
@@ -320,6 +322,7 @@ function createInjectedRoutes({ settings, cwd }: CreateRouteManifestParams): Rou
 			prerender: prerenderInjected ?? prerender,
 			fallbackRoutes: [],
 			distURL: [],
+			origin,
 		});
 	}
 
@@ -389,6 +392,7 @@ function createRedirectRoutes(
 			redirectRoute: routeMap.get(destination),
 			fallbackRoutes: [],
 			distURL: [],
+			origin: 'user',
 		});
 	}
 
@@ -727,6 +731,8 @@ export async function createRouteManifest(
 		}
 	}
 
+	await runHookRoutesResolved({ routes, settings, logger });
+
 	return {
 		routes,
 	};

packages/astro/src/core/routing/manifest/serialization.ts

@@ -41,5 +41,6 @@ export function deserializeRouteData(rawRouteData: SerializedRouteData): RouteDa
 			return deserializeRouteData(fallback);
 		}),
 		isIndex: rawRouteData.isIndex,
+		origin: rawRouteData.origin,
 	};
 }

packages/astro/src/core/server-islands/endpoint.ts

@@ -31,6 +31,7 @@ export function getServerIslandRouteData(config: ConfigFields) {
 		isIndex: false,
 		fallbackRoutes: [],
 		route: SERVER_ISLAND_ROUTE,
+		origin: 'core',
 	};
 	return route;
 }

packages/astro/src/integrations/hooks.ts

@@ -24,7 +24,9 @@ import type {
 import type {
 	AstroIntegration,
 	AstroRenderer,
+	BaseIntegrationHooks,
 	HookParameters,
+	IntegrationResolvedRoute,
 	IntegrationRouteData,
 	RouteOptions,
 } from '../types/public/integrations.js';
@@ -39,7 +41,7 @@ async function withTakingALongTimeMsg<T>({
 	logger,
 }: {
 	name: string;
-	hookName: string;
+	hookName: keyof BaseIntegrationHooks;
 	hookResult: T | Promise<T>;
 	timeoutMs?: number;
 	logger: Logger;
@@ -204,7 +206,7 @@ export async function runHookConfigSetup({
 						);
 						injectRoute.entrypoint = injectRoute.entryPoint as string;
 					}
-					updatedSettings.injectedRoutes.push(injectRoute);
+					updatedSettings.injectedRoutes.push({ ...injectRoute, origin: 'integration' });
 				},
 				addWatchFile: (path) => {
 					updatedSettings.watchFiles.push(path instanceof URL ? fileURLToPath(path) : path);
@@ -648,6 +650,38 @@ export async function runHookRouteSetup({
 	}
 }
 
+export async function runHookRoutesResolved({
+	routes,
+	settings,
+	logger,
+}: { routes: Array<RouteData>; settings: AstroSettings; logger: Logger }) {
+	for (const integration of settings.config.integrations) {
+		if (integration?.hooks?.['astro:routes:resolved']) {
+			const integrationLogger = getLogger(integration, logger);
+
+			await withTakingALongTimeMsg({
+				name: integration.name,
+				hookName: 'astro:routes:resolved',
+				hookResult: integration.hooks['astro:routes:resolved']({
+					routes: routes.map((route) => toIntegrationResolvedRoute(route)),
+					logger: integrationLogger,
+				}),
+				logger,
+			});
+		}
+	}
+}
+
+function toIntegrationResolvedRoute(route: RouteData): IntegrationResolvedRoute {
+	return {
+		prerendered: route.prerender,
+		entrypoint: route.component,
+		pattern: route.route,
+		params: route.params,
+		origin: route.origin,
+	};
+}
+
 function toIntegrationRouteData(route: RouteData): IntegrationRouteData {
 	return {
 		route: route.route,

packages/astro/src/types/astro.ts

@@ -10,12 +10,10 @@ import type { ContentEntryType, DataEntryType } from './public/content.js';
 import type {
 	AstroAdapter,
 	AstroRenderer,
-	InjectedRoute,
 	InjectedScriptStage,
 	InjectedType,
-	ResolvedInjectedRoute,
 } from './public/integrations.js';
-import type { RouteData } from './public/internal.js';
+import type { InternalInjectedRoute, RouteData, ResolvedInjectedRoute } from './public/internal.js';
 import type { DevToolbarAppEntry } from './public/toolbar.js';
 
 export type SerializedRouteData = Omit<
@@ -35,7 +33,7 @@ export interface AstroSettings {
 	config: AstroConfig;
 	adapter: AstroAdapter | undefined;
 	preferences: AstroPreferences;
-	injectedRoutes: InjectedRoute[];
+	injectedRoutes: InternalInjectedRoute[];
 	resolvedInjectedRoutes: ResolvedInjectedRoute[];
 	pageExtensions: string[];
 	contentEntryTypes: ContentEntryType[];

packages/astro/src/types/public/integrations.ts

@@ -8,7 +8,7 @@ import type { getToolbarServerCommunicationHelpers } from '../../integrations/ho
 import type { DeepPartial } from '../../type-utils.js';
 import type { AstroConfig } from './config.js';
 import type { RefreshContentOptions } from './content.js';
-import type { RouteData } from './internal.js';
+import type { InternalInjectedRoute, RouteData } from './internal.js';
 import type { DevToolbarAppEntry } from './toolbar.js';
 
 export interface RouteOptions {
@@ -138,15 +138,7 @@ export type AstroAdapterFeatureMap = {
  */
 export type InjectedScriptStage = 'before-hydration' | 'head-inline' | 'page' | 'page-ssr';
 
-export interface InjectedRoute {
-	pattern: string;
-	entrypoint: string | URL;
-	prerender?: boolean;
-}
-
-export interface ResolvedInjectedRoute extends InjectedRoute {
-	resolvedEntryPoint?: URL;
-}
+export type InjectedRoute = Omit<InternalInjectedRoute, 'origin'>;
 
 export interface InjectedType {
 	filename: string;
@@ -225,13 +217,18 @@ export interface BaseIntegrationHooks {
 	'astro:build:done': (options: {
 		pages: { pathname: string }[];
 		dir: URL;
+		/** @deprecated Use `routes` from `astro:routes:resolved` instead */
 		routes: IntegrationRouteData[];
 		logger: AstroIntegrationLogger;
 	}) => void | Promise<void>;
 	'astro:route:setup': (options: {
 		route: RouteOptions;
 		logger: AstroIntegrationLogger;
 	}) => void | Promise<void>;
+	'astro:routes:resolved': (options: {
+		routes: Array<IntegrationResolvedRoute>;
+		logger: AstroIntegrationLogger;
+	}) => void | Promise<void>;
 }
 
 export interface AstroIntegration {
@@ -248,10 +245,41 @@ export interface AstroIntegration {
  */
 export type IntegrationRouteData = Omit<
 	RouteData,
-	'isIndex' | 'fallbackRoutes' | 'redirectRoute'
+	'isIndex' | 'fallbackRoutes' | 'redirectRoute' | 'origin'
 > & {
 	/**
 	 * {@link RouteData.redirectRoute}
 	 */
 	redirectRoute?: IntegrationRouteData;
 };
+
+export interface IntegrationResolvedRoute {
+	/**
+	 * The current **pattern** of the route. For example:
+	 * - `src/pages/index.astro` has a pattern of `/`
+	 * - `src/pages/blog/[...slug].astro` has a pattern of `/blog/[...slug]`
+	 * - `src/pages/site/[blog]/[...slug].astro` has a pattern of `/site/[blog]/[...slug]`
+	 */
+	pattern: RouteData['route'];
+
+	/**
+	 *  Source component URL
+	 */
+	entrypoint: RouteData['component'];
+
+	/**
+	 * Whether the route is prerendered or not
+	 */
+	prerendered: RouteData['prerender'];
+
+	/**
+	 * Dynamic and spread route params
+	 * ex. "/pages/[lang]/[...slug].astro" will output the params ['lang', '...slug']
+	 */
+	params: RouteData['params'];
+
+	/**
+	 * Whether the route comes from Astro core, an integration or the user's project
+	 */
+	origin: RouteData['origin'];
+}

packages/astro/src/types/public/internal.ts

@@ -136,6 +136,11 @@ export interface RouteData {
 	 * - src/pages/blog/index.astro
 	 */
 	isIndex: boolean;
+
+	/**
+	 * Whether the route comes from Astro core, an integration or the user's project
+	 */
+	origin: 'core' | 'integration' | 'user';
 }
 
 /**
@@ -284,3 +289,14 @@ export interface SSRMetadata {
 }
 
 export type SSRError = Error & ViteErrorPayload['err'];
+
+export interface InternalInjectedRoute {
+	pattern: string;
+	entrypoint: string | URL;
+	prerender?: boolean;
+	origin: RouteData['origin'];
+}
+
+export interface ResolvedInjectedRoute extends InternalInjectedRoute {
+	resolvedEntryPoint?: URL;
+}