Polish unsupported metadata warning with doc link (#58750)

* Add docs link to the warning, add codemod link to viewport docs section
* Only log the warning once after the metadata resolving process, this will avoid multiple duplicated logs showing for one page.

Closes NEXT-1723

docs/02-app/02-api-reference/04-functions/generate-viewport.mdx

@@ -15,6 +15,7 @@ You can customize the initial viewport of the page with the static `viewport` ob
 >
 > - The `viewport` object and `generateViewport` function exports are **only supported in Server Components**.
 > - You cannot export both the `viewport` object and `generateViewport` function from the same route segment.
+> - If you're coming from migrating `metadata` exports, you can use [metadata-to-viewport-export codemod](/docs/app/building-your-application/upgrading/codemods#metadata-to-viewport-export) to update your changes.
 
 ## The `viewport` object
 

packages/next/src/lib/metadata/resolve-metadata.ts

@@ -63,6 +63,10 @@ type TitleTemplates = {
   openGraph: string | null
 }
 
+type BuildState = {
+  warnings: Set<string>
+}
+
 function hasIconsProperty(
   icons: Metadata['icons'],
   prop: 'icon' | 'apple'
@@ -135,12 +139,14 @@ function mergeMetadata({
   staticFilesMetadata,
   titleTemplates,
   metadataContext,
+  buildState,
 }: {
   source: Metadata | null
   target: ResolvedMetadata
   staticFilesMetadata: StaticMetadata
   titleTemplates: TitleTemplates
   metadataContext: MetadataContext
+  buildState: BuildState
 }): void {
   // If there's override metadata, prefer it otherwise fallback to the default metadata.
   const metadataBase =
@@ -244,8 +250,8 @@ function mergeMetadata({
           key === 'themeColor' ||
           key === 'colorScheme'
         ) {
-          Log.warn(
-            `Unsupported metadata ${key} is configured in metadata export. Please move it to viewport export instead.`
+          buildState.warnings.add(
+            `Unsupported metadata ${key} is configured in metadata export in ${metadataContext.pathname}. Please move it to viewport export instead.\nRead more: https://nextjs.org/docs/app/api-reference/functions/generate-viewport`
           )
         }
         break
@@ -685,6 +691,9 @@ export async function accumulateMetadata(
     resolvers: [],
     resolvingIndex: 0,
   }
+  const buildState = {
+    warnings: new Set<string>(),
+  }
   for (let i = 0; i < metadataItems.length; i++) {
     const staticFilesMetadata = metadataItems[i][1]
 
@@ -703,6 +712,7 @@ export async function accumulateMetadata(
       metadataContext,
       staticFilesMetadata,
       titleTemplates,
+      buildState,
     })
 
     // If the layout is the same layer with page, skip the leaf layout and leaf page
@@ -716,6 +726,13 @@ export async function accumulateMetadata(
     }
   }
 
+  // Only log warnings if there are any, and only once after the metadata resolving process is finished
+  if (buildState.warnings.size > 0) {
+    for (const warning of buildState.warnings) {
+      Log.warn(warning)
+    }
+  }
+
   return postProcessMetadata(resolvedMetadata, titleTemplates)
 }
 

test/e2e/app-dir/metadata-missing-metadata-base/app/unsupported-metadata/page.js

@@ -0,0 +1,7 @@
+export default function Page() {
+  return 'unsupported metadata'
+}
+
+export const metadata = {
+  themeColor: 'light',
+}

test/e2e/app-dir/metadata-missing-metadata-base/index.test.ts

@@ -1,34 +1,45 @@
-import { createNext, FileRef } from 'e2e-utils'
-import { NextInstance } from 'test/lib/next-modes/base'
-import { fetchViaHTTP, findPort } from 'next-test-utils'
+import { createNextDescribe } from 'e2e-utils'
+import { fetchViaHTTP } from 'next-test-utils'
 
-describe('app dir - metadata missing metadataBase', () => {
-  let next: NextInstance
-  let port: number
+createNextDescribe(
+  'app dir - metadata missing metadataBase',
+  {
+    files: __dirname,
+    skipDeployment: true,
+  },
+  ({ next, isNextStart }) => {
+    // If it's start mode, we get the whole logs since they're from build process.
+    // If it's dev mode, we get the logs after request
+    function getCliOutput(logStartPosition: number) {
+      return isNextStart
+        ? next.cliOutput
+        : next.cliOutput.slice(logStartPosition)
+    }
 
-  if ((global as any).isNextDeploy) {
-    return it('should skip for deploy', () => {})
-  }
-
-  beforeAll(async () => {
-    port = await findPort()
-    next = await createNext({
-      skipStart: true,
-      files: new FileRef(__dirname),
-      forcedPort: port + '',
+    it('should fallback to localhost if metadataBase is missing for absolute urls resolving', async () => {
+      const logStartPosition = next.cliOutput.length
+      await fetchViaHTTP(next.url, '/')
+      //
+      const output = getCliOutput(logStartPosition)
+      expect(output).toInclude(
+        'metadata.metadataBase is not set for resolving social open graph or twitter images,'
+      )
+      expect(output).toMatch(/using "http:\/\/localhost:\d+/)
+      expect(output).toInclude(
+        '. See https://nextjs.org/docs/app/api-reference/functions/generate-metadata#metadatabase'
+      )
     })
-  })
-  afterAll(() => next.destroy())
 
-  it('should fallback to localhost if metadataBase is missing for absolute urls resolving', async () => {
-    await next.start()
-    await fetchViaHTTP(next.url, '/')
-    expect(next.cliOutput).toInclude(
-      'metadata.metadataBase is not set for resolving social open graph or twitter images, using'
-    )
-    expect(next.cliOutput).toInclude(`"http://localhost:${port}`)
-    expect(next.cliOutput).toInclude(
-      '. See https://nextjs.org/docs/app/api-reference/functions/generate-metadata#metadatabase'
-    )
-  })
-})
+    it('should warn for unsupported metadata properties', async () => {
+      const logStartPosition = next.cliOutput.length
+      await fetchViaHTTP(next.url, '/unsupported-metadata')
+      const output = getCliOutput(logStartPosition)
+      expect(output).toInclude(
+        'Unsupported metadata themeColor is configured in metadata export in /unsupported-metadata. Please move it to viewport'
+      )
+      expect(output).toInclude(
+        'Read more: https://nextjs.org/docs/app/api-reference/functions/generate-viewport'
+      )
+    })
+  }
+)