fix(nuxt): prioritise later items in pages:routerOptions hook (#25509)

docs/2.guide/3.going-further/8.custom-routing.md

@@ -92,7 +92,7 @@ export default <RouterConfig> {
 }
 ```
 
-It is possible to add more router options files by adding files within the `pages:routerOptions` hook.
+It is possible to add more router options files by adding files within the `pages:routerOptions` hook. Later items in the array override earlier ones.
 
 ::alert
 Adding a router options file in this hook will switch on page-based routing, unless `optional` is set, in which case it will only apply when page-based routing is already enabled.

docs/3.api/6.advanced/1.hooks.md

@@ -50,7 +50,7 @@ Hook                     | Arguments                  | Description
 `builder:generateApp`    | `options`                  | Called before generating the app.
 `builder:watch`          | `event, path`              | Called at build time in development when the watcher spots a change to a file or directory in the project.
 `pages:extend`           | `pages`                    | Called after pages routes are resolved.
-`pages:routerOptions`   | `{ files: Array<{ path: string, optional?: boolean }> }` | Called when resolving `router.options` files.
+`pages:routerOptions`   | `{ files: Array<{ path: string, optional?: boolean }> }` | Called when resolving `router.options` files. Later items in the array override earlier ones.
 `server:devHandler`      | `handler`                  | Called when the dev middleware is being registered on the Nitro dev server.
 `imports:sources`        | `presets`                  | Called at setup allowing modules to extend sources.
 `imports:extend`         | `imports`                  | Called at setup allowing modules to extend imports.

packages/nuxt/src/pages/module.ts

@@ -35,14 +35,15 @@ export default defineNuxtModule({
       const context = {
         files: [] as Array<{ path: string, optional?: boolean }>
       }
-      // Add default options
-      context.files.push({ path: resolve(runtimeDir, 'router.options'), optional: true })
 
       for (const layer of nuxt.options._layers) {
         const path = await findPath(resolve(layer.config.srcDir, 'app/router.options'))
-        if (path) { context.files.push({ path }) }
+        if (path) { context.files.unshift({ path }) }
       }
 
+      // Add default options at beginning
+      context.files.unshift({ path: resolve(runtimeDir, 'router.options'), optional: true })
+
       await nuxt.callHook('pages:routerOptions', context)
       return context.files
     }
@@ -444,8 +445,7 @@ export default defineNuxtModule({
           `const configRouterOptions = ${configRouterOptions}`,
           'export default {',
           '...configRouterOptions,',
-          // We need to reverse spreading order to respect layers priority
-          ...routerOptionsFiles.map((_, index) => `...routerOptions${index},`).reverse(),
+          ...routerOptionsFiles.map((_, index) => `...routerOptions${index},`),
           '}'
         ].join('\n')
       }

packages/schema/src/types/hooks.ts

@@ -174,6 +174,8 @@ export interface NuxtHooks {
    * Called when resolving `app/router.options` files. It allows modifying the detected router options files
    * and adding new ones.
    *
+   * Later items in the array override earlier ones.
+   *
    * Adding a router options file will switch on page-based routing, unless `optional` is set, in which case
    * it will only apply when page-based routing is already enabled.
    * @param context An object with `files` containing an array of router options files.

test/fixtures/basic/nuxt.config.ts

@@ -39,8 +39,9 @@ export default defineNuxtConfig({
       }
     ]
   },
-  theme: './extends/bar',
   css: ['~/assets/global.css'],
+  // this produces an order of `~` > `~/extends/bar` > `~/extends/node_modules/foo`
+  theme: './extends/bar',
   extends: [
     './extends/node_modules/foo'
   ],