Repository: vercel/next.js
Pull request: Update generateMetadata in client component error

## What?

Improves the error shown when `generateMetadata` or `metadata` is exported from a Client Component.

Also updated the documentation to further explain why it can only be used in a server component and the steps to follow to resolve the error.

Changed files:
filename: crates/next-custom-transforms/src/transforms/react_server_components.rs
patch: @@ -334,7 +334,7 @@ fn report_error(app_dir: &Option<PathBuf>, filepath: &str, error_kind: RSCErrorK
             )
         },
         RSCErrorKind::NextRscErrClientMetadataExport((source, span)) => {
-            (format!("You are attempting to export \"{source}\" from a component marked with \"use client\", which is disallowed. Either remove the export, or the \"use client\" directive. Read more: https://nextjs.org/docs/app/api-reference/directives/use-client\n\n"), vec![span])
+            (format!("You are attempting to export \"{source}\" from a component marked with \"use client\", which is disallowed. \"{source}\" must be resolved on the server before the page component is rendered. Keep your page as a Server Component and move Client Component logic to a separate file. Read more: https://nextjs.org/docs/app/api-reference/functions/generate-metadata#why-generatemetadata-is-server-component-only\n\n"), vec![span])
         },
         RSCErrorKind::NextRscErrConflictMetadataExport((span1, span2)) => (
             "\"metadata\" and \"generateMetadata\" cannot be exported at the same time, please keep one of them. Read more: https://nextjs.org/docs/app/api-reference/file-conventions/metadata\n\n".to_string(),

filename: crates/next-custom-transforms/tests/errors/react-server-components/client-graph/generate-metadata/output.stderr
patch: @@ -1,5 +1,6 @@
-  x You are attempting to export "generateMetadata" from a component marked with "use client", which is disallowed. Either remove the export, or the "use client" directive. Read more: https://
-  | nextjs.org/docs/app/api-reference/directives/use-client
+  x You are attempting to export "generateMetadata" from a component marked with "use client", which is disallowed. "generateMetadata" must be resolved on the server before the page component is
+  | rendered. Keep your page as a Server Component and move Client Component logic to a separate file. Read more: https://nextjs.org/docs/app/api-reference/functions/generate-metadata#why-
+  | generatemetadata-is-server-component-only
   | 
   | 
    ,-[input.js:1:1]

filename: crates/next-custom-transforms/tests/errors/react-server-components/client-graph/metadata/output.stderr
patch: @@ -1,5 +1,6 @@
-  x You are attempting to export "metadata" from a component marked with "use client", which is disallowed. Either remove the export, or the "use client" directive. Read more: https://nextjs.org/
-  | docs/app/api-reference/directives/use-client
+  x You are attempting to export "metadata" from a component marked with "use client", which is disallowed. "metadata" must be resolved on the server before the page component is rendered. Keep your
+  | page as a Server Component and move Client Component logic to a separate file. Read more: https://nextjs.org/docs/app/api-reference/functions/generate-metadata#why-generatemetadata-is-server-
+  | component-only
   | 
   | 
    ,-[input.js:1:1]

filename: crates/next-custom-transforms/tests/errors/react-server-components/client-graph/multiple/output.stderr
patch: @@ -1,13 +1,15 @@
-  x You are attempting to export "metadata" from a component marked with "use client", which is disallowed. Either remove the export, or the "use client" directive. Read more: https://nextjs.org/
-  | docs/app/api-reference/directives/use-client
+  x You are attempting to export "metadata" from a component marked with "use client", which is disallowed. "metadata" must be resolved on the server before the page component is rendered. Keep your
+  | page as a Server Component and move Client Component logic to a separate file. Read more: https://nextjs.org/docs/app/api-reference/functions/generate-metadata#why-generatemetadata-is-server-
+  | component-only
   | 
   | 
    ,-[input.js:1:1]
  1 | export const metadata = {}
    :              ^^^^^^^^
    `----
-  x You are attempting to export "generateMetadata" from a component marked with "use client", which is disallowed. Either remove the export, or the "use client" directive. Read more: https://
-  | nextjs.org/docs/app/api-reference/directives/use-client
+  x You are attempting to export "generateMetadata" from a component marked with "use client", which is disallowed. "generateMetadata" must be resolved on the server before the page component is
+  | rendered. Keep your page as a Server Component and move Client Component logic to a separate file. Read more: https://nextjs.org/docs/app/api-reference/functions/generate-metadata#why-
+  | generatemetadata-is-server-component-only
   | 
   | 
    ,-[input.js:3:1]

filename: docs/01-app/03-api-reference/04-functions/generate-metadata.mdx
patch: @@ -113,6 +113,53 @@ For type completion of `params` and `searchParams`, you can type the first argum
 > - React [`cache` can be used](/docs/app/guides/caching#react-cache-function) if `fetch` is unavailable.
 > - [File-based metadata](/docs/app/api-reference/file-conventions/metadata) has the higher priority and will override the `metadata` object and `generateMetadata` function.
 
+## Why `generateMetadata` is Server Component only
+
+`generateMetadata` and the `metadata` export are only supported in Server Components because metadata must be resolved on the server before the page component is rendered. This allows Next.js to include the metadata in the initial HTML response.
+
+If you need to use Client Component features, keep your `page.tsx` as a Server Component and move the Client Component logic to a separate file:
+
+```tsx filename="app/page.tsx" switcher
+import type { Metadata } from 'next'
+import { InteractiveComponent } from './interactive-component'
+
+export const metadata: Metadata = {
+  title: 'My Page',
+}
+
+export default function Page() {
+  return <InteractiveComponent />
+}
+```
+
+```jsx filename="app/page.js" switcher
+import { InteractiveComponent } from './interactive-component'
+
+export const metadata = {
+  title: 'My Page',
+}
+
+export default function Page() {
+  return <InteractiveComponent />
+}
+```
+
+```tsx filename="app/interactive-component.tsx" switcher
+'use client'
+
+export function InteractiveComponent() {
+  // Client-side interactivity (hooks, event handlers, etc.)
+}
+```
+
+```jsx filename="app/interactive-component.js" switcher
+'use client'
+
+export function InteractiveComponent() {
+  // Client-side interactivity (hooks, event handlers, etc.)
+}
+```
+
 ## Reference
 
 ### Parameters