docs(nextjs): Document cache components limitations (#15899)

With more users adopting cache components and running into our current
limitations with it, we have to document it for them with the possible
workarounds.

None of these are ideal, but the way cache components interferes with
our core SDK behavior is not straightforward to fix and may need
fundamental changes to our core SDK.

For now I made sure we document the couple of wide cases that the issue
appears in, and possible workarounds (more like compromises).

---------

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Author: logaretm

docs/platforms/javascript/guides/nextjs/index.mdx

@@ -9,6 +9,8 @@ categories:
   - server-node
 ---
 
+<PlatformContent includePath="nextjs-cache-components-limitations/alert" />
+
 <PlatformContent includePath="llm-rules-platform" />
 
 <PlatformContent includePath="getting-started-prerequisites" />
@@ -328,6 +330,8 @@ Learn more about [Logs configuration](/platforms/javascript/guides/nextjs/logs/)
 
 </Expandable>
 
+<PlatformContent includePath="nextjs-cache-components-limitations/section" />
+
 ## Next Steps
 
 You've successfully integrated Sentry into your Next.js application! Here's what to explore next:

docs/platforms/javascript/guides/nextjs/manual-setup/index.mdx

@@ -15,6 +15,8 @@ categories:
   installer](/platforms/javascript/guides/nextjs).
 </Alert>
 
+<PlatformContent includePath="nextjs-cache-components-limitations/alert" />
+
 This guide covers manual setup for **Next.js 15+ with Turbopack and App Router**. For other setups, see:
 
 - [Pages Router Setup](/platforms/javascript/guides/nextjs/manual-setup/pages-router/) - For applications using the Pages Router
@@ -587,6 +589,10 @@ If your application uses both the App Router and Pages Router:
   the appropriate instrumentation.
 </Alert>
 
+<h2 data-no-number>Known Limitations</h2>
+
+<PlatformContent includePath="nextjs-cache-components-limitations/section" />
+
 <h2 data-no-number>Next Steps</h2>
 
 You've successfully integrated Sentry into your Next.js application! Here's what to explore next:

platform-includes/nextjs-cache-components-limitations/alert/javascript.nextjs.mdx

@@ -0,0 +1,5 @@
+<Alert level="warning" title="Cache Components Limitations">
+
+If you're using Next.js [Cache Components](https://nextjs.org/docs/app/getting-started/cache-components), there are known compatibility issues with server-side tracing. See [Cache Components Limitations](#cache-components-limitations) for details and workarounds.
+
+</Alert>

platform-includes/nextjs-cache-components-limitations/section/javascript.nextjs.mdx

@@ -0,0 +1,25 @@
+### Cache Components Limitations
+
+If you're using Next.js [Cache Components](https://nextjs.org/docs/app/getting-started/cache-components), you may encounter errors like:
+
+```
+Accessing random cryptographic values synchronously in a Server Component requires reading one of these data sources first...
+```
+
+#### Turbopack with `generateMetadata`
+
+Using `generateMetadata` in page components with Turbopack and the Sentry SDK is currently not supported. ([Tracking issue](https://github.com/getsentry/sentry-javascript/issues/18392))
+
+**Workarounds:**
+
+- Remove `generateMetadata` from affected page components
+- Disable server-side tracing by removing or renaming your `instrumentation.ts` file
+
+#### Webpack with Cache Components
+
+Cache Components are not supported when using webpack. ([Tracking issue](https://github.com/getsentry/sentry-javascript/issues/18340))
+
+**Workarounds:**
+
+- Switch to Turbopack (note the `generateMetadata` limitation above)
+- Disable server-side tracing by removing or renaming your `instrumentation.ts` file