docs: large page data error (#90920)

--- [Slack Thread](https://vercel.slack.com/archives/C08N392Q9EV/p1772698459867909?thread_ts=1772698459.867909&cid=C08N392Q9EV) <p><a href="https://cursor.com/agents/bc-f75e35d4-cde9-5300-8c76-b4a67c24d55f"><picture><source media="(prefers-color-scheme: dark)" srcset="https://cursor.com/assets/images/open-in-web-dark.png"><source media="(prefers-color-scheme: light)" srcset="https://cursor.com/assets/images/open-in-web-light.png"><img alt="Open in Web" width="114" height="28" src="https://cursor.com/assets/images/open-in-web-dark.png"></picture></a> <a href="https://cursor.com/background-agent?bcId=bc-f75e35d4-cde9-5300-8c76-b4a67c24d55f"><picture><source media="(prefers-color-scheme: dark)" srcset="https://cursor.com/assets/images/open-in-cursor-dark.png"><source media="(prefers-color-scheme: light)" srcset="https://cursor.com/assets/images/open-in-cursor-light.png"><img alt="Open in Cursor" width="131" height="28" src="https://cursor.com/assets/images/open-in-cursor-dark.png"></picture></a> </p>  --------- Co-authored-by: Cursor Agent <cursoragent@cursor.com> Co-authored-by: Joseph <icyJoseph@users.noreply.github.com>
2026-09-20 02:25:18 +08:00 · 2026-03-07 01:53:53 +01:00
parent 65fe53d421
commit 6155ca1722
1 changed files with 35 additions and 5 deletions
@@ -4,18 +4,48 @@ title: Large Page Data

 ## Why This Error Occurred

-One of your pages includes a large amount of page data (>= 128kB). This can negatively impact performance since page data must be parsed by the client before the page is hydrated.
+One of your pages includes a large amount of page data (> 128 kB). This warning only affects the Pages Router, where Next.js serializes page data as `__NEXT_DATA__` JSON, which the client must parse before hydrating the page. The App Router streams data via Server Components and is not affected.
+
+Large page data impacts performance in several ways:
+
+- **Increased page weight:** The serialized data is inlined in every HTML response, increasing the document size and slowing down the initial page load on slow networks.
+- **Slower hydration:** React cannot hydrate (make the page interactive) until the `__NEXT_DATA__` JSON has been parsed. Large payloads delay the [Time to Interactive (TTI)](https://web.dev/articles/tti).
+- **Higher memory usage:** The entire data payload is held in memory on the client, even if only part of it is used for rendering.

 ## Possible Ways to Fix It

-Reduce the amount of data returned from `getStaticProps`, `getServerSideProps`, or `getInitialProps` to only the essential data to render the page. The default threshold of 128kB can be configured in `largePageDataBytes` if absolutely necessary and the performance implications are understood.
+Return only the data your page needs to render from `getStaticProps`, `getServerSideProps`, or `getInitialProps`:

-To inspect the props passed to your page, you can inspect the below element's content in your browser devtools:
+- **Filter and trim data:** Only return the fields your components use. Avoid passing entire database records or API responses when only a subset of fields is needed.
+- **Paginate large lists:** Instead of returning hundreds of items at once, return a smaller initial set and fetch additional items on the client using API routes.
+- **Move data fetching to the client:** For non-critical content or content not visible on initial load, fetch it on the client side after hydration using `useEffect` or a data fetching library like [SWR](https://swr.vercel.app/) or [React Query](https://tanstack.com/query).

-```bash filename="Terminal"
+### Inspect your page data
+
+To inspect the data your page receives, open your browser DevTools console and run:
+
+```bash filename="Browser Console"
 JSON.parse(document.getElementById("__NEXT_DATA__").textContent)
 ```

+Use this to inspect the full payload and identify which fields are adding to the size.
+
+### Configure the threshold
+
+The default threshold of 128 kB is controlled by the `largePageDataBytes` option in `next.config.js`:
+
+```js filename="next.config.js"
+module.exports = {
+  experimental: {
+    largePageDataBytes: 200 * 1000, // Set threshold to 200 kB
+  },
+}
+```
+
+Before increasing this threshold, evaluate the performance implications to confirm the trade-off is acceptable for your use case.
+
 ## Useful Links

- [Data Fetching Documentation](/docs/pages/building-your-application/data-fetching)
+- [Pages Router Data Fetching](/docs/pages/building-your-application/data-fetching)
+- [SWR - React Hooks for Data Fetching](https://swr.vercel.app/)
+- [Time to Interactive (TTI)](https://web.dev/articles/tti)