Implement priority overrides for injected routes and redirects

.changeset/short-keys-bow.md

@@ -0,0 +1,15 @@
+---
+"astro": patch
+---
+
+Fix inconsistency between route priorities of file routes, redirects and injected routes
+
+
+Now all groups are prioritized following the same rules:
+
+- Routes with more path segments will take precedence over less specific routes. E.g. `/blog/post/[pid].astro` takes precedence over `/blog/[...slug].astro`.
+- Static routes without path parameters will take precedence over dynamic routes. E.g. `/posts/create.astro` takes precedence over all the other routes in the example.
+- Dynamic routes using named parameters take precedence over rest parameters. E.g. `/posts/[page].astro` takes precedence over `/posts/[...slug].astro`.
+- Pre-rendered dynamic routes take precedence over server dynamic routes.
+- Endpoints take precedence over pages. E.g. `/posts/[pid].ts` takes precedence over `/posts/[pid].astro`.
+- If none of the rules above decide the order, routes are sorted alphabetically based on the default locale of your Node installation.

.changeset/smooth-cobras-help.md

@@ -0,0 +1,34 @@
+---
+'astro': minor
+---
+
+Adds an experimental flag `stableRoutePriority` to make all routes be prioritized following the same stable rules.
+
+```js
+// astro.config.mjs
+{
+  experimental: {
+    stableRoutePriority: true,
+  },
+}
+```
+
+Enabling this feature makes redirects and injected routes be prioritized along with discovered file-based project
+routes, behaving the same as if all routes were defined as files in the project.
+
+For the following scenario in SSR mode:
+
+- File-based route: `/blog/post/[pid]`
+- File-based route: `/[page]`
+- Injected route: `/blog/[...slug]`
+- Redirect: `/blog/tags/[tag]` -> `/[tag]`
+- Redirect: `/posts` -> `/blog`
+
+URLs are handled with the following routes:
+
+| Page               | Current Behavior                 | Stable Routing Priority Behavior   |
+|--------------------|----------------------------------|------------------------------------|
+| `/blog/tags/astro` | Injected route `/blog/[...slug]` | Redirect to `/tags/[tag]`          |
+| `/blog/post/0`     | Injected route `/blog/[...slug]` | File-based route `/blog/post/[pid] |
+| `/posts`           | File-based route `/[page]`       | Redirect to `/blog`                |
+

packages/astro/src/@types/astro.ts

@@ -1566,6 +1566,33 @@ export interface AstroUserConfig {
 		 * ```
 		 */
 		contentCollectionCache?: boolean;
+
+		/**
+		 * @docs
+		 * @name experimental.globalRoutePriority
+		 * @type {boolean}
+		 * @default `false`
+		 * @version 4.2.0
+		 * @description
+		 *
+		 * Prioritize redirects and injected routes along with discovered file-based project routes, behaving the same as if all routes were defined as files in the project.
+		 *
+		 * For the following scenario in SSR mode:
+		 * - File-based route: `/blog/post/[pid]`
+		 * - File-based route: `/[page]`
+		 * - Injected route: `/blog/[...slug]`
+		 * - Redirect: `/blog/tags/[tag]` -> `/[tag]`
+		 * - Redirect: `/posts` -> `/blog`
+		 *
+		 * URLs are handled with the following routes:
+		 *
+		 * | Page               | Current Behavior                 | Stable Routing Priority Behavior   |
+		 * | ------------------ | -------------------------------- | ---------------------------------- |
+		 * | `/blog/tags/astro` | Injected route `/blog/[...slug]` | Redirect to `/tags/[tag]`          |
+		 * | `/blog/post/0`     | Injected route `/blog/[...slug]` | File-based route `/blog/post/[pid] |
+		 * | `/posts`           | File-based route `/[page]`       | Redirect to `/blog`                |
+		 */
+		globalRoutePriority?: boolean;
 	};
 }
 
@@ -1587,6 +1614,15 @@ export interface AstroUserConfig {
  */
 export type InjectedScriptStage = 'before-hydration' | 'head-inline' | 'page' | 'page-ssr';
 
+/**
+ * IDs for different priorities of injected routes and redirects:
+ * - "normal": Merge with discovered file-based project routes, behaving the same as if the route
+ *   was defined as a file in the project.
+ * - "legacy": Use the old ordering of routes. Inject routes will override any file-based project route,
+ *   and redirects will be overriden by any project route on conflict.
+ */
+export type RoutePriorityOverride = 'normal' | 'legacy';
+
 export interface InjectedRoute {
 	pattern: string;
 	entrypoint: string;
@@ -2431,6 +2467,7 @@ type RedirectConfig =
 	| {
 			status: ValidRedirectStatus;
 			destination: string;
+			priority?: RoutePriorityOverride;
 	  };
 
 export interface RouteData {

packages/astro/src/core/config/schema.ts

@@ -58,6 +58,7 @@ const ASTRO_CONFIG_DEFAULTS = {
 	experimental: {
 		optimizeHoistedScript: false,
 		contentCollectionCache: false,
+		globalRoutePriority: false,
 	},
 } satisfies AstroUserConfig & { server: { open: boolean } };
 
@@ -393,6 +394,10 @@ export const AstroConfigSchema = z.object({
 				.boolean()
 				.optional()
 				.default(ASTRO_CONFIG_DEFAULTS.experimental.contentCollectionCache),
+			globalRoutePriority: z
+				.boolean()
+				.optional()
+				.default(ASTRO_CONFIG_DEFAULTS.experimental.globalRoutePriority),
 		})
 		.strict(
 			`Invalid or outdated experimental feature.\nCheck for incorrect spelling or outdated Astro version.\nSee https://docs.astro.build/en/reference/configuration-reference/#experimental-flags for a list of all current experiments.`