Implement priority overrides for injected routes and redirects

.changeset/short-keys-bow.md

@@ -0,0 +1,16 @@
+---
+"astro": patch
+---
+
+Updates [Astro's routing priority rules](https://docs.astro.build/en/core-concepts/routing/#route-priority-order) to prioritize the most specifically-defined routes. 
+
+Now, routes with **more defined path segments** will take precedence over less-specific routes.
+
+For example, `/blog/posts/[pid].astro` (3 path segments) takes precedence over `/blog/[...slug].astro` (2 path segments). This means that:
+
+- `/pages/blog/posts/[id].astro` will build routes of the form `/blog/posts/1` and `/blog/posts/a`
+- `/pages/blog/[...slug].astro` will build routes of a variety of forms, including `blog/1` and `/blog/posts/1/a`, but will not build either of the previous routes.
+
+For a complete list of Astro's routing priority rules, please see the [routing guide](https://docs.astro.build/en/core-concepts/routing/#route-priority-order).
+
+

.changeset/smooth-cobras-help.md

@@ -0,0 +1,34 @@
+---
+'astro': minor
+---
+
+Adds an experimental flag `globalRoutePriority` to prioritize redirects and injected routes equally alongside file-based project routes, following the same [route priority order rules](https://docs.astro.build/en/core-concepts/routing/#route-priority-order) for all routes.
+
+```js
+// astro.config.mjs
+export default defineConfig({
+  experimental: {
+    globalRoutePriority: true,
+  },
+})
+```
+
+Enabling this feature ensures that all routes in your project follow the same, predictable route priority order rules. In particular, this avoids an issue where redirects or injected routes (e.g. from an integration) would always take precedence over local route definitions, making it impossible to override some routes locally.
+
+The following table shows which route builds certain page URLs when file-based routes, injected routes, and redirects are combined as shown below:
+
+- 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 by the following routes:
+
+| Page               | Current Behavior                 | Global 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`                 |
+
+In the event of route collisions, where two routes of equal route priority attempt to build the same URL, Astro will log a warning identifying the conflicting routes.

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

@@ -1566,6 +1566,36 @@ export interface AstroUserConfig {
 		 * ```
 		 */
 		contentCollectionCache?: boolean;
+
+		/**
+		 * @docs
+		 * @name experimental.globalRoutePriority
+		 * @type {boolean}
+		 * @default `false`
+		 * @version 4.2.0
+		 * @description
+		 *
+		 * Prioritizes redirects and injected routes equally alongside file-based project routes, following the same [route priority order rules](https://docs.astro.build/en/core-concepts/routing/#route-priority-order) for all routes.
+		 *
+		 * The following table shows which route builds certain page URLs when file-based routes, injected routes, and redirects are combined as shown below:
+		 * - 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 by the following routes:
+		 *
+		 * | Page               | Current Behavior                 | Global 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`                 |
+		 *
+		 *
+		 * In the event of route collisions, where two routes of equal route priority attempt to build the same URL, Astro will log a warning identifying the conflicting routes.
+		 */
+		globalRoutePriority?: boolean;
 	};
 }
 
@@ -1587,6 +1617,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 +2470,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.`