From faedfdffd9e231695dba40ccbcefc2935bdc0c0b Mon Sep 17 00:00:00 2001
From: Daniel Roe <daniel@roe.dev>
Date: Wed, 9 Oct 2024 16:50:33 +0200
Subject: [PATCH] fix: add `scanPageMeta: after-resolve` and enable for v4

---
 docs/1.getting-started/12.upgrade.md          | 21 +++++++++++++++++++
 .../1.experimental-features.md                |  2 ++
 docs/2.guide/3.going-further/1.features.md    |  1 +
 packages/nuxt/src/pages/utils.ts              | 20 +++++++++++++-----
 packages/schema/src/config/experimental.ts    |  7 ++++++-
 packages/schema/src/types/hooks.ts            |  6 +++---
 6 files changed, 48 insertions(+), 9 deletions(-)

diff --git a/docs/1.getting-started/12.upgrade.md b/docs/1.getting-started/12.upgrade.md
index 68cb635dc9..fde91e7fd2 100644
--- a/docs/1.getting-started/12.upgrade.md
+++ b/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
diff --git a/docs/2.guide/3.going-further/1.experimental-features.md b/docs/2.guide/3.going-further/1.experimental-features.md
index 31bed1a8ae..57cd77803e 100644
--- a/docs/2.guide/3.going-further/1.experimental-features.md
+++ b/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]
diff --git a/docs/2.guide/3.going-further/1.features.md b/docs/2.guide/3.going-further/1.features.md
index 247df516e2..46150d86d3 100644
--- a/docs/2.guide/3.going-further/1.features.md
+++ b/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,
diff --git a/packages/nuxt/src/pages/utils.ts b/packages/nuxt/src/pages/utils.ts
index 0b5074c539..25ef9ead8a 100644
--- a/packages/nuxt/src/pages/utils.ts
+++ b/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
diff --git a/packages/schema/src/config/experimental.ts b/packages/schema/src/config/experimental.ts
index 711a20b776..5743c313f0 100644
--- a/packages/schema/src/config/experimental.ts
+++ b/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
diff --git a/packages/schema/src/types/hooks.ts b/packages/schema/src/types/hooks.ts
index 585d36015a..aa9287a82f 100644
--- a/packages/schema/src/types/hooks.ts
+++ b/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
    */