fix: add scanPageMeta: after-resolve and enable for v4

docs/1.getting-started/12.upgrade.md

@@ -67,6 +67,7 @@ export default defineNuxtConfig({
   //   app: 'app'
   // },
   // experimental: {
+  //   scanPageMeta: 'after-resolve',
   //   sharedPrerenderData: false,
   //   compileTemplate: true,
   //   resetAsyncDataToUndefined: true,
@@ -236,6 +237,26 @@ export default defineNuxtConfig({
 })
 ```
 
+#### Scan Page Meta After Resolution
+
+🚦 **Impact Level**: Medium
+
+##### What Changed
+
+##### Reasons for Change
+
+##### Migration Steps
+
+Alternatively, for now, you can disable this behaviour with:
+
+```ts twoslash [nuxt.config.ts]
+export default defineNuxtConfig({
+  experimental: {
+    scanPageMeta: true
+  }
+})
+```
+
 #### Shared Prerender Data
 
 🚦 **Impact Level**: Medium

docs/2.guide/3.going-further/1.experimental-features.md

@@ -334,6 +334,8 @@ This option allows exposing some route metadata defined in `definePageMeta` at b
 
 This only works with static or strings/arrays rather than variables or conditional assignment. See [original issue](https://github.com/nuxt/nuxt/issues/24770) for more information and context.
 
+It is also possible to scan page metadata only after all routes have been registered in `pages:extend`. Then another hook, `pages:resolved` will be called. To enable this behavior, set `scanPageMeta: 'after-resolve'`.
+
 You can disable this feature if it causes issues in your project.
 
 ```ts twoslash [nuxt.config.ts]

docs/2.guide/3.going-further/1.features.md

@@ -61,6 +61,7 @@ export default defineNuxtConfig({
     app: 'app'
   },
   experimental: {
+    scanPageMeta: 'after-resolve',
     sharedPrerenderData: false,
     compileTemplate: true,
     resetAsyncDataToUndefined: true,

packages/nuxt/src/pages/utils.ts

@@ -63,14 +63,24 @@ export async function resolvePagesRoutes (): Promise<NuxtPage[]> {
     shouldUseServerComponents: !!nuxt.options.experimental.componentIslands,
   })
 
+  const pages = uniqueBy(allRoutes, 'path')
   const shouldAugment = nuxt.options.experimental.scanPageMeta || nuxt.options.experimental.typedPages
 
-  const pages = uniqueBy(allRoutes, 'path')
-
-  await nuxt.callHook('pages:extend', pages)
-  if (shouldAugment) {
-    await augmentPages(pages, nuxt.vfs)
+  if (shouldAugment === false) {
+    await nuxt.callHook('pages:extend', pages)
+    return pages
   }
+
+  if (shouldAugment === 'after-resolve') {
+    await nuxt.callHook('pages:extend', pages)
+    await augmentPages(pages, nuxt.vfs)
+  } else {
+    const augmentedPages = await augmentPages(pages, nuxt.vfs)
+    await nuxt.callHook('pages:extend', pages)
+    await augmentPages(pages, nuxt.vfs, augmentedPages)
+    augmentedPages.clear()
+  }
+
   await nuxt.callHook('pages:resolved', pages)
 
   return pages

packages/schema/src/config/experimental.ts

@@ -297,8 +297,13 @@ export default defineUntypedSchema({
      * This only works with static or strings/arrays rather than variables or conditional assignment.
      *
      * @see [Nuxt Issues #24770](https://github.com/nuxt/nuxt/issues/24770)
+     * @type {boolean | 'after-resolve'}
      */
-    scanPageMeta: true,
+    scanPageMeta: {
+      async $resolve (val, get) {
+        return val ?? ((await get('future') as Record<string, unknown>).compatibilityVersion === 4 ? 'after-resolve' : true)
+      },
+    },
 
     /**
      * Automatically share payload _data_ between pages that are prerendered. This can result in a significant

packages/schema/src/types/hooks.ts

@@ -183,14 +183,14 @@ export interface NuxtHooks {
   'builder:watch': (event: WatchEvent, path: string) => HookResult
 
   /**
-   * Called after pages routes are resolved.
-   * @param pages Array containing resolved pages
+   * Called after page routes are scanned from the file system.
+   * @param pages Array containing scanned pages
    * @returns Promise
    */
   'pages:extend': (pages: NuxtPage[]) => HookResult
 
   /**
-   * Called after pages routes are resolved.
+   * Called after page routes have been augmented with scanned metadata.
    * @param pages Array containing resolved pages
    * @returns Promise
    */